@effected/tsconfig-json 0.3.2 → 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,23 +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;
-/**
-* Project a {@link (ResolvedTsconfig:interface)} or a bare
-* `CompilerOptions.Type` down to a {@link (PortableTsconfig:interface)}: copy
-* only the allow-listed type-semantics options, force `composite: false` and
-* `noEmit: true` regardless of what the source declared, and stamp `$schema`.
-* Every other key — including every unknown passthrough key the source
-* preserved for forward tolerance — 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.
-*/
-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 {
@@ -126,13 +121,40 @@ const make = (input) => {
 	};
 };
 /**
-* The portable-tsconfig filter: {@link (PortableTsconfig:variable).make}
+* The portable-tsconfig filter: {@link (PortableTsconfig:class).make}
 * narrows a resolved or bare compiler-options object to the allow-listed,
 * machine-independent subset described on {@link (PortableTsconfig:interface)}.
 *
 * @public
 */
-const PortableTsconfig = { make };
+var PortableTsconfig = class {
+	constructor() {}
+	/**
+	* Project a {@link (ResolvedTsconfig:interface)} or a bare
+	* `CompilerOptions.Type` down to a {@link (PortableTsconfig:interface)}:
+	* copy only the allow-listed type-semantics options, force
+	* `composite: false` and `noEmit: true` regardless of what the source
+	* declared, and stamp `$schema`. Every other key — including every
+	* unknown passthrough key the source preserved for forward tolerance —
+	* 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;
+};
 
 //#endregion
 export { PortableTsconfig };

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/ResolvedTsconfig.js

@@ -72,16 +72,6 @@ const transformCompilerOptionPaths = (co, transform, includePathsValues) => {
 	}
 	return out;
 };
-/**
-* Absolutize a config's path-typed options (E5) against its own `configDir`,
-* using the injected `join` (`Path.Path.resolve` at the call site — so an
-* already-absolute value is preserved). `${configDir}`-prefixed values are
-* exempt (resolved later, in {@link (ResolvedTsconfig:variable).substituteConfigDir}), and
-* `paths` VALUES stay verbatim. Only `compilerOptions` path surfaces are
-* touched; `files`/`include`/`exclude` are re-rooted at merge time instead (E4).
-*
-* @public
-*/
 const absolutize = (doc, configDir, join) => {
 	const co = doc.compilerOptions;
 	if (co === void 0) return doc;
@@ -153,14 +143,6 @@ const mergeWatchOptions = (base, derived) => {
 		...derived
 	};
 };
-/**
-* Fold one more-derived config onto the accumulated base (E4), derived winning.
-* The loader (Task 8) applies this across the resolution chain, own config last.
-* `derivedPath` is the derived config's absolute normalized path, from which the
-* re-rooting frame and `pathsBase` are computed.
-*
-* @public
-*/
 const merge = (base, derived, derivedPath) => {
 	const finalDir = dirname(derivedPath);
 	const baseDir = dirname(base.configPath);
@@ -202,15 +184,6 @@ const substituteWatchExcludes = (wo, substitute) => {
 	}
 	return out;
 };
-/**
-* The E5 final phase: replace a leading `${configDir}` token (case-insensitive,
-* leading position only) with `finalDir` — the top-level extending config's
-* directory — across every eligible surface: compilerOptions path options,
-* `paths` values, `files`/`include`/`exclude`, and `watchOptions`'
-* `excludeDirectories`/`excludeFiles`. Every other field is left untouched.
-*
-* @public
-*/
 const substituteConfigDir = (resolved, finalDir) => {
 	const substitute = (value) => startsWithConfigDir(value) ? finalDir + value.slice(CONFIG_DIR_TEMPLATE.length) : value;
 	const compilerOptions = transformCompilerOptionPaths(resolved.compilerOptions, substitute, true);
@@ -229,16 +202,42 @@ const substituteConfigDir = (resolved, finalDir) => {
 };
 /**
 * The pure extends-merge engine: parse-time path absolutization
-* ({@link (ResolvedTsconfig:variable).absolutize}), the per-field merge fold
-* ({@link (ResolvedTsconfig:variable).merge}), and the `${configDir}` final
-* phase ({@link (ResolvedTsconfig:variable).substituteConfigDir}).
+* ({@link (ResolvedTsconfig:class).absolutize}), the per-field merge fold
+* ({@link (ResolvedTsconfig:class).merge}), and the `${configDir}` final
+* phase ({@link (ResolvedTsconfig:class).substituteConfigDir}).
 *
 * @public
 */
-const ResolvedTsconfig = {
-	absolutize,
-	merge,
-	substituteConfigDir
+var ResolvedTsconfig = class {
+	constructor() {}
+	/**
+	* Absolutize a config's path-typed options (E5) against its own
+	* `configDir`, using the injected `join` (`Path.Path.resolve` at the call
+	* site — so an already-absolute value is preserved). `${configDir}`-prefixed
+	* values are exempt (resolved later, in
+	* {@link (ResolvedTsconfig:class).substituteConfigDir}), and `paths`
+	* VALUES stay verbatim. Only `compilerOptions` path surfaces are touched;
+	* `files`/`include`/`exclude` are re-rooted at merge time instead (E4).
+	*/
+	static absolutize = absolutize;
+	/**
+	* Fold one more-derived config onto the accumulated base (E4), derived
+	* winning. The loader (Task 8) applies this across the resolution chain,
+	* own config last. `derivedPath` is the derived config's absolute
+	* normalized path, from which the re-rooting frame and `pathsBase` are
+	* computed.
+	*/
+	static merge = merge;
+	/**
+	* The E5 final phase: replace a leading `${configDir}` token
+	* (case-insensitive, leading position only) with `finalDir` — the
+	* top-level extending config's directory — across every eligible
+	* surface: compilerOptions path options, `paths` values,
+	* `files`/`include`/`exclude`, and `watchOptions`'
+	* `excludeDirectories`/`excludeFiles`. Every other field is left
+	* untouched.
+	*/
+	static substituteConfigDir = substituteConfigDir;
 };
 
 //#endregion

package/TsEnumCodec.js

@@ -94,31 +94,8 @@ const TABLES = {
 		["fixedchunksize", 3]
 	])
 };
-/**
-* Encodes a family's canonical (or alias) string spelling to its numeric
-* form. `Option.none()` for a string with no table entry — never guessed.
-*
-* @public
-*/
 const encode = (family, value) => Option.fromNullishOr(TABLES[family].forward.get(value));
-/**
-* Decodes a family's numeric value to its canonical string spelling.
-* `Option.none()` for a numeric value with no table entry (a future TS enum
-* member) — never guessed.
-*
-* @public
-*/
 const decode = (family, value) => Option.fromNullishOr(TABLES[family].reverse.get(value));
-/**
-* Normalizes any spelling of a `lib` reference — the plain short name
-* (`esnext`), the on-disk file name (`lib.esnext.d.ts`), or an absolute path
-* to one (`/…/typescript/lib/lib.dom.iterable.d.ts`) — to the canonical
-* lowercase short name (`esnext`, `dom.iterable`). Strips a leading
-* directory, the `lib.` prefix and the `.d.ts` suffix; idempotent on an
-* already-short name.
-*
-* @public
-*/
 const normalizeLibReference = (lib) => {
 	const base = (lib.split("/").pop() ?? lib).toLowerCase();
 	const withoutPrefix = base.startsWith("lib.") ? base.slice(4) : base;
@@ -133,24 +110,6 @@ const COMPILER_OPTION_ENUM_KEYS = [
 	["newLine", "newLine"],
 	["moduleDetection", "moduleDetection"]
 ];
-/**
-* Encodes a decoded `compilerOptions` object into the numeric-enum-shaped
-* {@link ProgrammaticCompilerOptions} form `ts.CompilerOptions` (and
-* `@typescript/vfs`'s `TsEnvironment`) expect: every R1.6 enum family becomes
-* its numeric value, and `lib` entries become the file-name form
-* (`lib.esnext.d.ts`) — see the module banner for the evidence. Every other key
-* (booleans, strings, arrays, unknown passthrough keys) is copied through
-* untouched.
-*
-* The return carries this package's single narrowing from the codec's internal
-* `Record<string, unknown>` (whose values include the schema's `unknown`
-* passthrough and its `readonly` arrays) to {@link ProgrammaticCompilerOptions}
-* — see that type's docs for why the package owns this one assertion instead of
-* leaving every consumer to cast. Runtime behavior is unchanged; only the
-* declared return type narrows.
-*
-* @public
-*/
 const encodeCompilerOptions = (options) => {
 	const source = options;
 	const result = { ...source };
@@ -165,20 +124,6 @@ const encodeCompilerOptions = (options) => {
 	if (Array.isArray(lib)) result.lib = lib.map((entry) => typeof entry === "string" ? `lib.${normalizeLibReference(entry)}.d.ts` : entry);
 	return result;
 };
-/**
-* Decodes a numeric-enum-shaped `compilerOptions` object (as produced by
-* {@link (TsEnumCodec:variable).encodeCompilerOptions} or read off a live
-* `ts.CompilerOptions`) back into the string-enum shape this package's
-* schemas use: every R1.6 enum family becomes its canonical string, and
-* `lib` entries become the short form. A numeric value with no table entry —
-* a future TS enum member — is left as-is (passthrough, never an error) —
-* which is why the return type stays the wider `Record<string, unknown>`
-* rather than {@link (CompilerOptions:variable).Type}: an unmappable
-* passthrough value would violate that narrower type's contract. Every other
-* key is copied through untouched.
-*
-* @public
-*/
 const decodeCompilerOptions = (numeric) => {
 	const result = { ...numeric };
 	for (const [key, family] of COMPILER_OPTION_ENUM_KEYS) {
@@ -199,12 +144,61 @@ const decodeCompilerOptions = (numeric) => {
 *
 * @public
 */
-const TsEnumCodec = {
-	encode,
-	decode,
-	normalizeLibReference,
-	encodeCompilerOptions,
-	decodeCompilerOptions
+var TsEnumCodec = class {
+	constructor() {}
+	/**
+	* Encodes a family's canonical (or alias) string spelling to its numeric
+	* form. `Option.none()` for a string with no table entry — never guessed.
+	*/
+	static encode = encode;
+	/**
+	* Decodes a family's numeric value to its canonical string spelling.
+	* `Option.none()` for a numeric value with no table entry (a future TS
+	* enum member) — never guessed.
+	*/
+	static decode = decode;
+	/**
+	* Normalizes any spelling of a `lib` reference — the plain short name
+	* (`esnext`), the on-disk file name (`lib.esnext.d.ts`), or an absolute
+	* path to one (`/…/typescript/lib/lib.dom.iterable.d.ts`) — to the
+	* canonical lowercase short name (`esnext`, `dom.iterable`). Strips a
+	* leading directory, the `lib.` prefix and the `.d.ts` suffix; idempotent
+	* on an already-short name.
+	*/
+	static normalizeLibReference = normalizeLibReference;
+	/**
+	* Encodes a decoded `compilerOptions` object into the
+	* numeric-enum-shaped {@link ProgrammaticCompilerOptions} form
+	* `ts.CompilerOptions` (and `@typescript/vfs`'s `TsEnvironment`) expect:
+	* every R1.6 enum family becomes its numeric value, and `lib` entries
+	* become the file-name form (`lib.esnext.d.ts`) — see the module banner
+	* for the evidence. Every other key (booleans, strings, arrays, unknown
+	* passthrough keys) is copied through untouched.
+	*
+	* @remarks
+	* The return carries this package's single narrowing from the codec's
+	* internal `Record<string, unknown>` (whose values include the schema's
+	* `unknown` passthrough and its `readonly` arrays) to
+	* {@link ProgrammaticCompilerOptions} — see that type's docs for why the
+	* package owns this one assertion instead of leaving every consumer to
+	* cast. Runtime behavior is unchanged; only the declared return type
+	* narrows.
+	*/
+	static encodeCompilerOptions = encodeCompilerOptions;
+	/**
+	* Decodes a numeric-enum-shaped `compilerOptions` object (as produced by
+	* {@link TsEnumCodec.encodeCompilerOptions} or read off a live
+	* `ts.CompilerOptions`) back into the string-enum shape this package's
+	* schemas use: every R1.6 enum family becomes its canonical string, and
+	* `lib` entries become the short form. A numeric value with no table
+	* entry — a future TS enum member — is left as-is (passthrough, never an
+	* error) — which is why the return type stays the wider
+	* `Record<string, unknown>` rather than
+	* {@link (CompilerOptions:namespace).Type}: an unmappable passthrough
+	* value would violate that narrower type's contract. Every other key is
+	* copied through untouched.
+	*/
+	static decodeCompilerOptions = decodeCompilerOptions;
 };
 
 //#endregion

package/TsconfigDiscovery.js

@@ -2,16 +2,6 @@ import { Effect, Path } from "effect";
 import { Walker } from "@effected/walker";
 
 //#region src/TsconfigDiscovery.ts
-/**
-* Find the nearest `tsconfig.json` (or `options.filename`) at or above
-* `start`, ascending toward the filesystem root. Absence — nowhere on the
-* chain, or every candidate unreadable — is `Option.none()`, never an error;
-* discovery is best-effort per `Walker.findUpward`'s absorption posture, and a
-* permission-denied probe on one directory does not hide a config file above
-* it.
-*
-* @public
-*/
 const findNearest = (start, options) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const filename = options?.filename ?? "tsconfig.json";
@@ -23,7 +13,18 @@ const findNearest = (start, options) => Effect.gen(function* () {
 *
 * @public
 */
-const TsconfigDiscovery = { findNearest };
+var TsconfigDiscovery = class {
+	constructor() {}
+	/**
+	* Find the nearest `tsconfig.json` (or `options.filename`) at or above
+	* `start`, ascending toward the filesystem root. Absence — nowhere on the
+	* chain, or every candidate unreadable — is `Option.none()`, never an
+	* error; discovery is best-effort per `Walker.findUpward`'s absorption
+	* posture, and a permission-denied probe on one directory does not hide a
+	* config file above it.
+	*/
+	static findNearest = findNearest;
+};
 
 //#endregion
 export { TsconfigDiscovery };

package/TsconfigLoader.js

@@ -58,14 +58,6 @@ const loadAbs = (abs) => Effect.gen(function* () {
 		cause
 	})));
 });
-/**
-* Read one config file and decode it through {@link TsconfigJsonFromString}. A
-* decode failure is wrapped in a {@link TsconfigParseError} carrying the file's
-* absolute path; a `PlatformError` from the read flows through untranslated. No
-* `extends` resolution — {@link TsconfigLoader.resolve} drives that.
-*
-* @public
-*/
 const load = Effect.fn("TsconfigLoader.load")(function* (configPath) {
 	const path = yield* Path.Path;
 	return yield* loadAbs(normalizeSlashes(path.resolve(configPath)));
@@ -119,19 +111,6 @@ const collect = (configPath, chain) => Effect.gen(function* () {
 	});
 	return layers;
 });
-/**
-* Resolve a tsconfig.json and its full `extends` chain into a
-* {@link (ResolvedTsconfig:interface)}: load and decode each config, absolutize its path
-* options (E5), resolve `extends` depth-first with per-branch cycle and depth
-* guards (E1-E3, E6), fold the chain own-config-last (E4), then substitute a
-* leading `${configDir}` once against the top config's directory (E5 final
-* phase). `configPath` + `extendedPaths` come back base-most first, own config
-* last. Every failure is a typed error — `TsconfigParseError` (a malformed file,
-* carrying that file's path), `TsconfigExtendsError` (a broken chain), or a
-* `PlatformError` from IO — never a defect.
-*
-* @public
-*/
 const resolve = Effect.fn("TsconfigLoader.resolve")(function* (configPath) {
 	const path = yield* Path.Path;
 	const topAbs = normalizeSlashes(path.resolve(configPath));
@@ -144,14 +123,6 @@ const resolve = Effect.fn("TsconfigLoader.resolve")(function* (configPath) {
 	for (const entry of layers) acc = ResolvedTsconfig.merge(acc, entry.doc, entry.path);
 	return ResolvedTsconfig.substituteConfigDir(acc, path.dirname(topAbs));
 });
-/**
-* Resolve a tsconfig.json's full `extends` chain and project out the merged
-* `compilerOptions` — a thin projection of {@link TsconfigLoader.resolve} for
-* the common "just give me the effective options" query. Same pipeline, same
-* typed failures.
-*
-* @public
-*/
 const compilerOptions = Effect.fn("TsconfigLoader.compilerOptions")(function* (configPath) {
 	return (yield* resolve(configPath)).compilerOptions;
 });
@@ -163,10 +134,36 @@ const compilerOptions = Effect.fn("TsconfigLoader.compilerOptions")(function* (c
 *
 * @public
 */
-const TsconfigLoader = {
-	load,
-	resolve,
-	compilerOptions
+var TsconfigLoader = class {
+	constructor() {}
+	/**
+	* Read one config file and decode it through {@link TsconfigJsonFromString}.
+	* A decode failure is wrapped in a {@link TsconfigParseError} carrying the
+	* file's absolute path; a `PlatformError` from the read flows through
+	* untranslated. No `extends` resolution — {@link TsconfigLoader.resolve}
+	* drives that.
+	*/
+	static load = load;
+	/**
+	* Resolve a tsconfig.json and its full `extends` chain into a
+	* {@link (ResolvedTsconfig:interface)}: load and decode each config,
+	* absolutize its path options (E5), resolve `extends` depth-first with
+	* per-branch cycle and depth guards (E1-E3, E6), fold the chain
+	* own-config-last (E4), then substitute a leading `${configDir}` once
+	* against the top config's directory (E5 final phase). `configPath` +
+	* `extendedPaths` come back base-most first, own config last. Every
+	* failure is a typed error — `TsconfigParseError` (a malformed file,
+	* carrying that file's path), `TsconfigExtendsError` (a broken chain), or
+	* a `PlatformError` from IO — never a defect.
+	*/
+	static resolve = resolve;
+	/**
+	* Resolve a tsconfig.json's full `extends` chain and project out the
+	* merged `compilerOptions` — a thin projection of
+	* {@link TsconfigLoader.resolve} for the common "just give me the
+	* effective options" query. Same pipeline, same typed failures.
+	*/
+	static compilerOptions = compilerOptions;
 };
 
 //#endregion

package/TsconfigLoaderSync.js

@@ -67,30 +67,8 @@ const runWith = (options, effect) => {
 	if (Result.isSuccess(defect)) throw defect.success;
 	throw Cause.squash(exit.cause);
 };
-/**
-* {@link TsconfigLoader.load}, synchronously: read and decode one config file
-* through the consumer-supplied operations. Throws `TsconfigParseError` or a
-* `PlatformError` — the async pipeline's exact typed failures.
-*
-* @public
-*/
 const load = (configPath, options) => runWith(options, TsconfigLoader.load(configPath));
-/**
-* {@link TsconfigLoader.resolve}, synchronously: the full load -\> extends -\>
-* merge -\> `${configDir}` pipeline through the consumer-supplied operations.
-* Throws `TsconfigParseError`, `TsconfigExtendsError` or a `PlatformError` —
-* the async pipeline's exact typed failures.
-*
-* @public
-*/
 const resolve = (configPath, options) => runWith(options, TsconfigLoader.resolve(configPath));
-/**
-* {@link TsconfigLoader.compilerOptions}, synchronously: resolve the full
-* `extends` chain and project out the merged `compilerOptions`. Throws the
-* same typed failures as {@link TsconfigLoaderSync.resolve}.
-*
-* @public
-*/
 const compilerOptions = (configPath, options) => resolve(configPath, options).compilerOptions;
 /**
 * The synchronous tsconfig.json loader facade: the {@link TsconfigLoader}
@@ -121,10 +99,29 @@ const compilerOptions = (configPath, options) => resolve(configPath, options).co
 *
 * @public
 */
-const TsconfigLoaderSync = {
-	load,
-	resolve,
-	compilerOptions
+var TsconfigLoaderSync = class {
+	constructor() {}
+	/**
+	* {@link TsconfigLoader.load}, synchronously: read and decode one config
+	* file through the consumer-supplied operations. Throws
+	* `TsconfigParseError` or a `PlatformError` — the async pipeline's exact
+	* typed failures.
+	*/
+	static load = load;
+	/**
+	* {@link TsconfigLoader.resolve}, synchronously: the full load -\>
+	* extends -\> merge -\> `${configDir}` pipeline through the
+	* consumer-supplied operations. Throws `TsconfigParseError`,
+	* `TsconfigExtendsError` or a `PlatformError` — the async pipeline's exact
+	* typed failures.
+	*/
+	static resolve = resolve;
+	/**
+	* {@link TsconfigLoader.compilerOptions}, synchronously: resolve the full
+	* `extends` chain and project out the merged `compilerOptions`. Throws
+	* the same typed failures as {@link TsconfigLoaderSync.resolve}.
+	*/
+	static compilerOptions = compilerOptions;
 };
 
 //#endregion

package/index.d.ts

@@ -550,17 +550,43 @@ interface ResolvedTsconfig {
 }
 /**
  * The pure extends-merge engine: parse-time path absolutization
- * ({@link (ResolvedTsconfig:variable).absolutize}), the per-field merge fold
- * ({@link (ResolvedTsconfig:variable).merge}), and the `${configDir}` final
- * phase ({@link (ResolvedTsconfig:variable).substituteConfigDir}).
+ * ({@link (ResolvedTsconfig:class).absolutize}), the per-field merge fold
+ * ({@link (ResolvedTsconfig:class).merge}), and the `${configDir}` final
+ * phase ({@link (ResolvedTsconfig:class).substituteConfigDir}).
  *
  * @public
  */
-declare const ResolvedTsconfig: {
-  readonly absolutize: (doc: TsconfigJson.Type, configDir: string, join: (a: string, b: string) => string) => TsconfigJson.Type;
-  readonly merge: (base: ResolvedTsconfig, derived: TsconfigJson.Type, derivedPath: string) => ResolvedTsconfig;
-  readonly substituteConfigDir: (resolved: ResolvedTsconfig, finalDir: string) => ResolvedTsconfig;
-};
+declare class ResolvedTsconfig {
+  private constructor();
+  /**
+   * Absolutize a config's path-typed options (E5) against its own
+   * `configDir`, using the injected `join` (`Path.Path.resolve` at the call
+   * site — so an already-absolute value is preserved). `${configDir}`-prefixed
+   * values are exempt (resolved later, in
+   * {@link (ResolvedTsconfig:class).substituteConfigDir}), and `paths`
+   * VALUES stay verbatim. Only `compilerOptions` path surfaces are touched;
+   * `files`/`include`/`exclude` are re-rooted at merge time instead (E4).
+   */
+  static readonly absolutize: (doc: TsconfigJson.Type, configDir: string, join: (a: string, b: string) => string) => TsconfigJson.Type;
+  /**
+   * Fold one more-derived config onto the accumulated base (E4), derived
+   * winning. The loader (Task 8) applies this across the resolution chain,
+   * own config last. `derivedPath` is the derived config's absolute
+   * normalized path, from which the re-rooting frame and `pathsBase` are
+   * computed.
+   */
+  static readonly merge: (base: ResolvedTsconfig, derived: TsconfigJson.Type, derivedPath: string) => ResolvedTsconfig;
+  /**
+   * The E5 final phase: replace a leading `${configDir}` token
+   * (case-insensitive, leading position only) with `finalDir` — the
+   * top-level extending config's directory — across every eligible
+   * surface: compilerOptions path options, `paths` values,
+   * `files`/`include`/`exclude`, and `watchOptions`'
+   * `excludeDirectories`/`excludeFiles`. Every other field is left
+   * untouched.
+   */
+  static readonly substituteConfigDir: (resolved: ResolvedTsconfig, finalDir: string) => ResolvedTsconfig;
+}
 //#endregion
 //#region src/PortableTsconfig.d.ts
 /**
@@ -578,15 +604,62 @@ interface PortableTsconfig {
   readonly compilerOptions: Record<string, unknown>;
 }
 /**
- * The portable-tsconfig filter: {@link (PortableTsconfig:variable).make}
+ * 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,
  * machine-independent subset described on {@link (PortableTsconfig:interface)}.
  *
  * @public
  */
-declare const PortableTsconfig: {
-  readonly make: (input: ResolvedTsconfig | CompilerOptions.Type) => PortableTsconfig;
-};
+declare class PortableTsconfig {
+  private constructor();
+  /**
+   * Project a {@link (ResolvedTsconfig:interface)} or a bare
+   * `CompilerOptions.Type` down to a {@link (PortableTsconfig:interface)}:
+   * copy only the allow-listed type-semantics options, force
+   * `composite: false` and `noEmit: true` regardless of what the source
+   * declared, and stamp `$schema`. Every other key — including every
+   * unknown passthrough key the source preserved for forward tolerance —
+   * 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, options?: PortableTsconfigOptions) => PortableTsconfig;
+}
 //#endregion
 //#region src/TsconfigDiscovery.d.ts
 /**
@@ -605,9 +678,18 @@ interface FindNearestOptions {
  *
  * @public
  */
-declare const TsconfigDiscovery: {
-  readonly findNearest: (start: string, options?: FindNearestOptions) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem | Path.Path>;
-};
+declare class TsconfigDiscovery {
+  private constructor();
+  /**
+   * Find the nearest `tsconfig.json` (or `options.filename`) at or above
+   * `start`, ascending toward the filesystem root. Absence — nowhere on the
+   * chain, or every candidate unreadable — is `Option.none()`, never an
+   * error; discovery is best-effort per `Walker.findUpward`'s absorption
+   * posture, and a permission-denied probe on one directory does not hide a
+   * config file above it.
+   */
+  static readonly findNearest: (start: string, options?: FindNearestOptions) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem | Path.Path>;
+}
 //#endregion
 //#region src/TsconfigLoader.d.ts
 declare const TsconfigExtendsError_base: Schema.Class<TsconfigExtendsError, Schema.TaggedStruct<"TsconfigExtendsError", {
@@ -642,8 +724,16 @@ declare class TsconfigExtendsError extends TsconfigExtendsError_base {
  *
  * @public
  */
-declare const TsconfigLoader: {
-  readonly load: (configPath: string) => Effect.Effect<{
+declare class TsconfigLoader {
+  private constructor();
+  /**
+   * Read one config file and decode it through {@link TsconfigJsonFromString}.
+   * A decode failure is wrapped in a {@link TsconfigParseError} carrying the
+   * file's absolute path; a `PlatformError` from the read flows through
+   * untranslated. No `extends` resolution — {@link TsconfigLoader.resolve}
+   * drives that.
+   */
+  static readonly load: (configPath: string) => Effect.Effect<{
     readonly [x: string]: unknown;
     readonly compilerOptions?: {
       readonly [x: string]: unknown;
@@ -790,8 +880,26 @@ declare const TsconfigLoader: {
     readonly compileOnSave?: boolean | undefined;
     readonly $schema?: string | undefined;
   }, PlatformError.PlatformError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
-  readonly resolve: (configPath: string) => Effect.Effect<ResolvedTsconfig, PlatformError.PlatformError | TsconfigExtendsError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
-  readonly compilerOptions: (configPath: string) => Effect.Effect<{
+  /**
+   * Resolve a tsconfig.json and its full `extends` chain into a
+   * {@link (ResolvedTsconfig:interface)}: load and decode each config,
+   * absolutize its path options (E5), resolve `extends` depth-first with
+   * per-branch cycle and depth guards (E1-E3, E6), fold the chain
+   * own-config-last (E4), then substitute a leading `${configDir}` once
+   * against the top config's directory (E5 final phase). `configPath` +
+   * `extendedPaths` come back base-most first, own config last. Every
+   * failure is a typed error — `TsconfigParseError` (a malformed file,
+   * carrying that file's path), `TsconfigExtendsError` (a broken chain), or
+   * a `PlatformError` from IO — never a defect.
+   */
+  static readonly resolve: (configPath: string) => Effect.Effect<ResolvedTsconfig, PlatformError.PlatformError | TsconfigExtendsError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * Resolve a tsconfig.json's full `extends` chain and project out the
+   * merged `compilerOptions` — a thin projection of
+   * {@link TsconfigLoader.resolve} for the common "just give me the
+   * effective options" query. Same pipeline, same typed failures.
+   */
+  static readonly compilerOptions: (configPath: string) => Effect.Effect<{
     readonly [x: string]: unknown;
     readonly target?: "es2015" | "es2016" | "es2017" | "es2018" | "es2019" | "es2020" | "es2021" | "es2022" | "es2023" | "es2024" | "es2025" | "es5" | "es6" | "esnext" | undefined;
     readonly module?: "amd" | "commonjs" | "es2015" | "es2020" | "es2022" | "es6" | "esnext" | "node16" | "node18" | "node20" | "nodenext" | "none" | "preserve" | "system" | "umd" | undefined;
@@ -909,7 +1017,7 @@ declare const TsconfigLoader: {
     }[] | undefined;
     readonly maxNodeModuleJsDepth?: number | undefined;
   }, PlatformError.PlatformError | TsconfigExtendsError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
-};
+}
 //#endregion
 //#region src/TsconfigLoaderSync.d.ts
 /**
@@ -1012,11 +1120,30 @@ interface TsconfigLoaderSyncOptions {
  *
  * @public
  */
-declare const TsconfigLoaderSync: {
-  readonly load: (configPath: string, options: TsconfigLoaderSyncOptions) => TsconfigJson.Type;
-  readonly resolve: (configPath: string, options: TsconfigLoaderSyncOptions) => ResolvedTsconfig;
-  readonly compilerOptions: (configPath: string, options: TsconfigLoaderSyncOptions) => CompilerOptions.Type;
-};
+declare class TsconfigLoaderSync {
+  private constructor();
+  /**
+   * {@link TsconfigLoader.load}, synchronously: read and decode one config
+   * file through the consumer-supplied operations. Throws
+   * `TsconfigParseError` or a `PlatformError` — the async pipeline's exact
+   * typed failures.
+   */
+  static readonly load: (configPath: string, options: TsconfigLoaderSyncOptions) => TsconfigJson.Type;
+  /**
+   * {@link TsconfigLoader.resolve}, synchronously: the full load -\>
+   * extends -\> merge -\> `${configDir}` pipeline through the
+   * consumer-supplied operations. Throws `TsconfigParseError`,
+   * `TsconfigExtendsError` or a `PlatformError` — the async pipeline's exact
+   * typed failures.
+   */
+  static readonly resolve: (configPath: string, options: TsconfigLoaderSyncOptions) => ResolvedTsconfig;
+  /**
+   * {@link TsconfigLoader.compilerOptions}, synchronously: resolve the full
+   * `extends` chain and project out the merged `compilerOptions`. Throws
+   * the same typed failures as {@link TsconfigLoaderSync.resolve}.
+   */
+  static readonly compilerOptions: (configPath: string, options: TsconfigLoaderSyncOptions) => CompilerOptions.Type;
+}
 //#endregion
 //#region src/TsEnumCodec.d.ts
 /**
@@ -1068,7 +1195,7 @@ type ProgrammaticCompilerOptionsValue = string | number | boolean | (string | nu
   readonly circular?: boolean;
 }[] | null | undefined;
 /**
- * The shape {@link (TsEnumCodec:variable).encodeCompilerOptions} returns: the
+ * The shape {@link TsEnumCodec.encodeCompilerOptions} returns: the
  * numeric-enum-encoded `compilerOptions` a virtual-TS environment and the
  * TypeScript compiler API consume programmatically.
  *
@@ -1115,13 +1242,62 @@ interface ProgrammaticCompilerOptions {
  *
  * @public
  */
-declare const TsEnumCodec: {
-  readonly encode: (family: EnumFamily, value: string) => Option.Option<number>;
-  readonly decode: (family: EnumFamily, value: number) => Option.Option<string>;
-  readonly normalizeLibReference: (lib: string) => string;
-  readonly encodeCompilerOptions: (options: CompilerOptions.Type) => ProgrammaticCompilerOptions;
-  readonly decodeCompilerOptions: (numeric: Readonly<Record<string, unknown>>) => Record<string, unknown>;
-};
+declare class TsEnumCodec {
+  private constructor();
+  /**
+   * Encodes a family's canonical (or alias) string spelling to its numeric
+   * form. `Option.none()` for a string with no table entry — never guessed.
+   */
+  static readonly encode: (family: EnumFamily, value: string) => Option.Option<number>;
+  /**
+   * Decodes a family's numeric value to its canonical string spelling.
+   * `Option.none()` for a numeric value with no table entry (a future TS
+   * enum member) — never guessed.
+   */
+  static readonly decode: (family: EnumFamily, value: number) => Option.Option<string>;
+  /**
+   * Normalizes any spelling of a `lib` reference — the plain short name
+   * (`esnext`), the on-disk file name (`lib.esnext.d.ts`), or an absolute
+   * path to one (`/…/typescript/lib/lib.dom.iterable.d.ts`) — to the
+   * canonical lowercase short name (`esnext`, `dom.iterable`). Strips a
+   * leading directory, the `lib.` prefix and the `.d.ts` suffix; idempotent
+   * on an already-short name.
+   */
+  static readonly normalizeLibReference: (lib: string) => string;
+  /**
+   * Encodes a decoded `compilerOptions` object into the
+   * numeric-enum-shaped {@link ProgrammaticCompilerOptions} form
+   * `ts.CompilerOptions` (and `@typescript/vfs`'s `TsEnvironment`) expect:
+   * every R1.6 enum family becomes its numeric value, and `lib` entries
+   * become the file-name form (`lib.esnext.d.ts`) — see the module banner
+   * for the evidence. Every other key (booleans, strings, arrays, unknown
+   * passthrough keys) is copied through untouched.
+   *
+   * @remarks
+   * The return carries this package's single narrowing from the codec's
+   * internal `Record<string, unknown>` (whose values include the schema's
+   * `unknown` passthrough and its `readonly` arrays) to
+   * {@link ProgrammaticCompilerOptions} — see that type's docs for why the
+   * package owns this one assertion instead of leaving every consumer to
+   * cast. Runtime behavior is unchanged; only the declared return type
+   * narrows.
+   */
+  static readonly encodeCompilerOptions: (options: CompilerOptions.Type) => ProgrammaticCompilerOptions;
+  /**
+   * Decodes a numeric-enum-shaped `compilerOptions` object (as produced by
+   * {@link TsEnumCodec.encodeCompilerOptions} or read off a live
+   * `ts.CompilerOptions`) back into the string-enum shape this package's
+   * schemas use: every R1.6 enum family becomes its canonical string, and
+   * `lib` entries become the short form. A numeric value with no table
+   * entry — a future TS enum member — is left as-is (passthrough, never an
+   * error) — which is why the return type stays the wider
+   * `Record<string, unknown>` rather than
+   * {@link (CompilerOptions:namespace).Type}: an unmappable passthrough
+   * value would violate that narrower type's contract. Every other key is
+   * copied through untouched.
+   */
+  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.2",
+	"version": "0.4.0",
 	"private": false,
 	"description": "Composable tsconfig.json handling for Effect: schemas, extends-chain resolution, and config discovery.",
 	"keywords": [
@@ -40,7 +40,7 @@
 	},
 	"peerDependencies": {
 		"@effected/jsonc": "~0.5.1",
-		"@effected/walker": "~0.3.2",
+		"@effected/walker": "~0.3.3",
 		"effect": "4.0.0-beta.101"
 	},
 	"engines": {