@effected/tsconfig-json 0.6.0 → 0.7.0

package/CompilerOptionsFromProgrammatic.js

@@ -0,0 +1,52 @@
+import { CompilerOptions } from "./CompilerOptions.js";
+import { TsEnumCodec } from "./TsEnumCodec.js";
+import { Schema, SchemaTransformation } from "effect";
+
+//#region src/CompilerOptionsFromProgrammatic.ts
+const normalizeIn = (input) => TsEnumCodec.decodeCompilerOptions(input);
+const encodeOut = (encoded) => TsEnumCodec.encodeCompilerOptions(encoded);
+/**
+* A codec between the **programmatic** `compilerOptions` shape TypeScript's own
+* API uses and this package's decoded {@link (CompilerOptions:namespace).Type}.
+*
+* Decoding accepts the numeric-enum spelling (`{ target: ts.ScriptTarget.ES2025 }`),
+* the canonical string spelling, case-varying strings (`"ESNext"`), any mixture of
+* the three in one object, and `lib` entries in any of their three spellings
+* (`"esnext"`, `"lib.esnext.d.ts"`, an absolute path to the lib file) — producing
+* validated {@link (CompilerOptions:namespace).Type} with canonical lowercase enum
+* strings and short-form `lib`. Unknown and dead keys pass through, exactly as
+* {@link (CompilerOptions:variable)} itself allows. Decoding is idempotent on
+* already-canonical input.
+*
+* Encoding is {@link TsEnumCodec.encodeCompilerOptions}: numeric enum values and
+* `lib` in the file-name form (`lib.esnext.d.ts`).
+*
+* @remarks
+* A numeric value with no table entry — a future TypeScript enum member — survives
+* normalization as a number and then **fails decode** with a typed schema issue,
+* rather than passing through. That is deliberate: this is the validating door
+* {@link TsEnumCodec.decodeCompilerOptions} is not, which is why that function's
+* return type stays the wider `Record<string, unknown>`.
+*
+* @example
+* ```ts
+* import { Schema } from "effect";
+* import { CompilerOptionsFromProgrammatic } from "@effected/tsconfig-json";
+*
+* // { target: "es2025", strict: true, lib: ["esnext"] }
+* Schema.decodeUnknownSync(CompilerOptionsFromProgrammatic)({
+* 	target: 12,
+* 	strict: true,
+* 	lib: ["lib.esnext.d.ts"],
+* });
+* ```
+*
+* @public
+*/
+const CompilerOptionsFromProgrammatic = Schema.Record(Schema.String, Schema.Unknown).pipe(Schema.decodeTo(CompilerOptions, SchemaTransformation.transform({
+	decode: normalizeIn,
+	encode: encodeOut
+})));
+
+//#endregion
+export { CompilerOptionsFromProgrammatic };

package/README.md

@@ -114,7 +114,7 @@ const compilerOptions = TsconfigLoaderSync.compilerOptions("./tsconfig.json", op
 TypeScript 7's native `tsc` ships a version-only stub as its `.` export — there is no JS compiler API behind it. A package that drives the typechecker as a library (`@typescript/vfs`, the language service, the Program API) can neither type against nor runtime-load a TypeScript 7 install, and the obvious fix of pinning the dev `typescript` back to 6 forfeits the native `tsc` and leaves toolchain peers on `^7` unmet. The recipe that keeps both starts here, because this package is what removes the compile-time half of the dependency.
 
 1. Type against the tsconfig JSON form, not the compiler. Public option types use `CompilerOptions.Type` — `{ target: "es2022" }`, strings all the way down — so nothing in `src` or the tests imports `typescript`, not even as a type. The dev `typescript` stays on 7, native `tsc --noEmit` still runs the typecheck, and the toolchain's `^7` peer stays satisfied.
-2. Convert at a single runtime seam. `TsEnumCodec.encodeCompilerOptions` maps the string form to the numeric enums a real compiler expects and returns `ProgrammaticCompilerOptions`, the shape a `ts.CompilerOptions`-typed API takes without a cast. Only that one call site knows a compiler exists.
+2. Convert at a single runtime seam. `TsEnumCodec.encodeCompilerOptions` maps the string form to the numeric enums a real compiler expects and returns `ProgrammaticCompilerOptions`, the shape a `ts.CompilerOptions`-typed API takes without a cast. Only that one call site knows a compiler exists. The inbound direction is `CompilerOptionsFromProgrammatic`, a schema rather than a function: hand it a live `ts.CompilerOptions`, a numeric enum literal or the output of `encodeCompilerOptions` and validated `CompilerOptions.Type` comes back, with an unmappable numeric failing decode instead of leaking through.
 3. Alias a classic install for the test runtime, where the JS API is genuinely needed: a dev-only `"typescript-classic": "npm:typescript@^6.0.3"` plus a vitest `resolve.alias` mapping `typescript` to it. The consumer-facing peer stays an optional `^6` — runtime-only, for callers of the compiler-touching module.
 4. Pass `tsLibDirectory` explicitly when you drive `@typescript/vfs`. It locates `lib.*.d.ts` through `require.resolve("typescript")`, which under this setup resolves the TypeScript 7 install, and that install has no lib directory: the map comes back **empty**, silently, with no error to follow. Derive the directory from the module you actually loaded.
 
@@ -159,6 +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.
+- `CompilerOptionsFromProgrammatic` — the same tables as a validating codec, for callers holding TypeScript's programmatic spelling. Decode accepts numeric enums, canonical strings, case-varying strings, any mixture of the three and `lib` in any of its three spellings; encode returns the numeric form. A numeric with no table entry fails decode as a typed schema issue rather than passing through, which is the check `TsEnumCodec.decodeCompilerOptions` deliberately does not make.
 - `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

@@ -190,6 +190,59 @@ declare namespace CompilerOptions {
   type Encoded = typeof CompilerOptions.Encoded;
 }
 //#endregion
+//#region src/CompilerOptionsFromProgrammatic.d.ts
+/**
+ * The untyped record this codec accepts on its encoded side. Exported because
+ * it names the codec's encoded type in the public signature; the values stay
+ * `unknown` rather than {@link ProgrammaticCompilerOptionsValue} because decode
+ * validates them and must be able to receive anything, including the
+ * unmappable numeric it exists to reject.
+ *
+ * @public
+ */
+interface ProgrammaticRecord {
+  readonly [key: string]: unknown;
+}
+/**
+ * A codec between the **programmatic** `compilerOptions` shape TypeScript's own
+ * API uses and this package's decoded {@link (CompilerOptions:namespace).Type}.
+ *
+ * Decoding accepts the numeric-enum spelling (`{ target: ts.ScriptTarget.ES2025 }`),
+ * the canonical string spelling, case-varying strings (`"ESNext"`), any mixture of
+ * the three in one object, and `lib` entries in any of their three spellings
+ * (`"esnext"`, `"lib.esnext.d.ts"`, an absolute path to the lib file) — producing
+ * validated {@link (CompilerOptions:namespace).Type} with canonical lowercase enum
+ * strings and short-form `lib`. Unknown and dead keys pass through, exactly as
+ * {@link (CompilerOptions:variable)} itself allows. Decoding is idempotent on
+ * already-canonical input.
+ *
+ * Encoding is {@link TsEnumCodec.encodeCompilerOptions}: numeric enum values and
+ * `lib` in the file-name form (`lib.esnext.d.ts`).
+ *
+ * @remarks
+ * A numeric value with no table entry — a future TypeScript enum member — survives
+ * normalization as a number and then **fails decode** with a typed schema issue,
+ * rather than passing through. That is deliberate: this is the validating door
+ * {@link TsEnumCodec.decodeCompilerOptions} is not, which is why that function's
+ * return type stays the wider `Record<string, unknown>`.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect";
+ * import { CompilerOptionsFromProgrammatic } from "@effected/tsconfig-json";
+ *
+ * // { target: "es2025", strict: true, lib: ["esnext"] }
+ * Schema.decodeUnknownSync(CompilerOptionsFromProgrammatic)({
+ * 	target: 12,
+ * 	strict: true,
+ * 	lib: ["lib.esnext.d.ts"],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const CompilerOptionsFromProgrammatic: Schema.Codec<typeof CompilerOptions.Type, ProgrammaticRecord>;
+//#endregion
 //#region src/JsxConfig.d.ts
 declare const JsxConfig_base: Schema.Class<JsxConfig, Schema.Struct<{
   /** The JSX transform runtime: `"automatic"` (`react-jsx` / `react-jsxdev`) or `"classic"` (`react`). */
@@ -1299,5 +1352,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 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 };
+export { CompilerOptions, CompilerOptionsFromProgrammatic, type EnumFamily, FallbackPolling, type FindNearestOptions, Jsx, JsxConfig, Lib, Module, ModuleDetection, ModuleResolution, NewLine, PortableTsconfig, type PortableTsconfigOptions, type ProgrammaticCompilerOptions, type ProgrammaticCompilerOptionsValue, type ProgrammaticRecord, 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/index.js

@@ -1,4 +1,6 @@
 import { CompilerOptions, Jsx, Lib, Module, ModuleDetection, ModuleResolution, NewLine, Target } from "./CompilerOptions.js";
+import { TsEnumCodec } from "./TsEnumCodec.js";
+import { CompilerOptionsFromProgrammatic } from "./CompilerOptionsFromProgrammatic.js";
 import { JsxConfig } from "./JsxConfig.js";
 import { PortableTsconfig } from "./PortableTsconfig.js";
 import { ResolvedTsconfig } from "./ResolvedTsconfig.js";
@@ -6,6 +8,5 @@ import { TsconfigDiscovery } from "./TsconfigDiscovery.js";
 import { FallbackPolling, Reference, TsconfigJson, TsconfigJsonFromString, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions } from "./TsconfigJson.js";
 import { TsconfigExtendsError, TsconfigLoader } from "./TsconfigLoader.js";
 import { TsconfigLoaderSync } from "./TsconfigLoaderSync.js";
-import { TsEnumCodec } from "./TsEnumCodec.js";
 
-export { CompilerOptions, FallbackPolling, Jsx, JsxConfig, Lib, Module, ModuleDetection, ModuleResolution, NewLine, PortableTsconfig, Reference, ResolvedTsconfig, Target, TsEnumCodec, TsconfigDiscovery, TsconfigExtendsError, TsconfigJson, TsconfigJsonFromString, TsconfigLoader, TsconfigLoaderSync, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions };
+export { CompilerOptions, CompilerOptionsFromProgrammatic, FallbackPolling, Jsx, JsxConfig, Lib, Module, ModuleDetection, ModuleResolution, NewLine, PortableTsconfig, Reference, ResolvedTsconfig, Target, TsEnumCodec, TsconfigDiscovery, TsconfigExtendsError, TsconfigJson, TsconfigJsonFromString, TsconfigLoader, TsconfigLoaderSync, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/tsconfig-json",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"private": false,
 	"description": "Composable tsconfig.json handling for Effect: schemas, extends-chain resolution, and config discovery.",
 	"keywords": [
@@ -39,7 +39,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.7.0",
+		"@effected/jsonc": "^0.8.1",
 		"@effected/walker": "^0.5.0",
 		"effect": "4.0.0-rc.109"
 	},

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.12"
+      "packageVersion": "7.59.0"
     }
   ]
 }