Merge pull request #202 from ping-maxwell/experimental

fix(experimental): export FnErrorsOf for portable declaration emit

Author: ping-maxwell

packages/experimental/src/declaration-emit.test.ts

@@ -1,12 +1,22 @@
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	symlinkSync,
+	writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const fixtureDir = join(root, "test/declaration-emit");
+const consumerFixtureDir = join(root, "test/declaration-emit-consumer");
+const tsc = join(root, "../../node_modules/typescript/bin/tsc");
 
 /** Soft ceiling well under TS7056 (~1e6 chars). Pre-fix auth emits were
  * ~750KB for two fns because ScopeOf/ResolvedVars inlined the module graph. */
@@ -18,13 +28,7 @@ describe("declaration emit (TS7056)", () => {
 		try {
 			execFileSync(
 				process.execPath,
-				[
-					join(root, "../../node_modules/typescript/bin/tsc"),
-					"-p",
-					join(fixtureDir, "tsconfig.json"),
-					"--outDir",
-					outDir,
-				],
+				[tsc, "-p", join(fixtureDir, "tsconfig.json"), "--outDir", outDir],
 				{ cwd: root, stdio: "pipe" },
 			);
 
@@ -45,3 +49,64 @@ describe("declaration emit (TS7056)", () => {
 		}
 	});
 });
+
+describe("declaration emit (TS2883 / package entry)", () => {
+	it("exports e.fn with errors through better-call package entry under node16", () => {
+		expect(
+			existsSync(join(root, "dist/index.d.mts")),
+			"dist/index.d.mts missing - run pnpm build in packages/experimental",
+		).toBe(true);
+
+		const consumerDir = mkdtempSync(join(tmpdir(), "bc-decl-consumer-"));
+		try {
+			mkdirSync(join(consumerDir, "node_modules"));
+			symlinkSync(root, join(consumerDir, "node_modules/better-call"));
+			symlinkSync(
+				join(consumerFixtureDir, "index.ts"),
+				join(consumerDir, "index.ts"),
+			);
+			symlinkSync(
+				join(consumerFixtureDir, "tsconfig.json"),
+				join(consumerDir, "tsconfig.json"),
+			);
+			// Written here (not checked in) so this fixture is not a pnpm
+			// workspace package that knip would police for unlisted deps.
+			writeFileSync(
+				join(consumerDir, "package.json"),
+				JSON.stringify({
+					name: "better-call-declaration-emit-consumer",
+					private: true,
+					type: "module",
+				}),
+			);
+
+			try {
+				execFileSync(process.execPath, [tsc, "-p", "tsconfig.json"], {
+					cwd: consumerDir,
+					stdio: "pipe",
+				});
+			} catch (err) {
+				const e = err as { stderr?: Buffer; stdout?: Buffer };
+				throw new Error(
+					[
+						"consumer declaration emit failed:",
+						e.stderr?.toString("utf8"),
+						e.stdout?.toString("utf8"),
+					]
+						.filter(Boolean)
+						.join("\n"),
+				);
+			}
+
+			const dts = readFileSync(join(consumerDir, "out/index.d.ts"), "utf8");
+			expect(dts).toMatch(/export declare const signInEmail:/);
+			expect(dts).toMatch(/export declare const bound:/);
+			// Portable via package entry - not better-call/dist/fn.mjs (TS2883).
+			expect(dts).toMatch(/import\("better-call"\)\.FnErrorsOf/);
+			expect(dts).toMatch(/import\("better-call"\)\.BoundCall/);
+			expect(dts).not.toMatch(/dist\/fn\.mjs/);
+		} finally {
+			rmSync(consumerDir, { recursive: true, force: true });
+		}
+	});
+});

packages/experimental/src/fn.ts

@@ -91,7 +91,9 @@ type CallArgs<A, I> = I extends readonly unknown[]
 			? [input?: A, parent?: ParentContext]
 			: [input: A, parent?: ParentContext];
 
-/** The union of a fn's DECLARED errors, as thrown values. */
+/** The union of a fn's DECLARED errors, as thrown values.
+ * Re-exported from the package entry - `.try` / used-fn results surface
+ * this in inferred types, and declaration emit needs a portable name. */
 export type FnErrorsOf<Er> = {
 	[T in keyof Er & string]: FnError<T, InferInput<Er[T]>>;
 }[keyof Er & string];
@@ -191,7 +193,9 @@ type PublicFn<
 	O = unknown,
 > = FnDefination<A, R, K, I, P, Er, WithSeed<RV, U>, O>;
 
-/** What `.with` returns: the same callable, context baked in. */
+/** What `.with` returns: the same callable, context baked in.
+ * Re-exported from the package entry so exporting `.with(...)` results
+ * stays declaration-emit portable under node16. */
 export interface BoundCall<A, R, I, Er> {
 	(...args: CallArgs<A, I>): R;
 	try(...args: CallArgs<A, I>): TryResult<R, Er>;

packages/experimental/src/index.ts

@@ -103,10 +103,12 @@ export {
 	ValidationError,
 } from "./error";
 export type {
+	BoundCall,
 	Context,
 	Fn,
 	FnDefination,
 	FnErrors,
+	FnErrorsOf,
 	Instance,
 	OptionType,
 	ParentContext,

packages/experimental/test/declaration-emit-consumer/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Dependent-package fixture: import through the published "better-call"
+ * entry (package exports), export an e.fn that declares errors and uses
+ * another error-declaring fn. Under moduleResolution node16, declaration
+ * emit must name types only via the package entry - see
+ * `declaration-emit.test.ts` (TS2883 / formerly TS2742).
+ */
+import { v } from "better-call";
+
+const loadUser = v.fn(
+	"loadUser",
+	{
+		errors: {
+			not_found: { id: v.string() },
+			denied: { reason: v.string() },
+		},
+	},
+	(c): { id: string } => {
+		if (Math.random() > 0.5) throw c.error("not_found", { id: "x" });
+		return { id: "1" };
+	},
+);
+
+const e = v.fn("auth.", { use: [{ loadUser }] });
+
+export const signInEmail = e.fn(
+	"sign_in.email",
+	{
+		input: { email: v.string(), password: v.string() },
+		errors: {
+			invalid_credentials: {},
+			locked: { until: v.date() },
+		},
+	},
+	async (c) => {
+		const r = c.loadUser();
+		if (!r.ok) throw c.error("invalid_credentials");
+		return { user: r.value };
+	},
+);
+
+export const bound = signInEmail.with({});

packages/experimental/test/declaration-emit-consumer/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"strict": true,
+		"declaration": true,
+		"emitDeclarationOnly": true,
+		"outDir": "./out",
+		"module": "Node16",
+		"moduleResolution": "Node16",
+		"target": "ESNext",
+		"skipLibCheck": true,
+		"lib": ["esnext"]
+	},
+	"include": ["./index.ts"]
+}