@neondatabase/env 0.0.0

package/src/lib/test-utils.ts

@@ -0,0 +1,83 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { vi } from "vitest";
+
+/**
+ * Every Neon env var (and adjacent OS env var) the platform package reads at runtime.
+ * Used by {@link stubCleanNeonEnv} to give each test a deterministic, empty starting
+ * env regardless of the developer's local `~/.config/neonctl`, exported `NEON_*` vars,
+ * or anything else carried over from the parent shell.
+ */
+const NEON_AND_RELATED_ENV_KEYS = [
+	"NEON_API_KEY",
+	"NEON_PROJECT_ID",
+	"NEON_BRANCH_ID",
+	"NEON_ORG_ID",
+	"NEON_AUTH_BASE_URL",
+	"NEON_DATA_API_URL",
+	"DATABASE_URL",
+	"DATABASE_URL_UNPOOLED",
+	"NEONCTL_CONFIG_DIR",
+	"HOME",
+	"USERPROFILE",
+] as const;
+
+/**
+ * Stub every Neon-related env var to `undefined` (so they look unset to the code under
+ * test). Tests can override individual keys with `vi.stubEnv(key, value)` after calling
+ * this. `vitest.config.ts` sets `unstubEnvs: true` so each test's stubs are auto-reset.
+ *
+ * Call this from a `beforeEach` in any test file that touches `process.env`-driven
+ * resolution (api key / context / connection-string env vars).
+ */
+export function stubCleanNeonEnv(): void {
+	for (const key of NEON_AND_RELATED_ENV_KEYS) {
+		// vitest 3.x: passing `undefined` deletes the env var (rather than setting it
+		// to the literal string "undefined") — exactly what we want, because empty
+		// strings would still trip code that reads `env.HOME` to build paths.
+		vi.stubEnv(key, undefined);
+	}
+}
+
+/**
+ * Build a transient project tree under the OS temp directory.
+ *
+ * Returns the absolute root path plus a `cleanup()` that removes the tree. Tests should
+ * call `cleanup()` from an `afterEach`/`afterAll` hook.
+ *
+ * `files` is a flat map of relative paths → contents; intermediate directories are created
+ * automatically. Directories themselves can be created by passing `null` as the value.
+ *
+ * A `.git/HEAD` marker is seeded at the root by default so the platform's upward walkers
+ * (which stop at `.git`) don't escape the synthetic repo and read the developer's real
+ * `~/.neon`. Pass an explicit `.git` entry in `files` to override or position it elsewhere
+ * (e.g. for tests that exercise the boundary behaviour itself).
+ */
+export function makeTempRepo(files: Record<string, string | null>): {
+	root: string;
+	cleanup: () => void;
+} {
+	const root = mkdtempSync(join(tmpdir(), "neon-ts-test-"));
+	const callerSpecifiesGit = Object.keys(files).some(
+		(p) => p === ".git" || p.startsWith(".git/"),
+	);
+	const entries: Array<[string, string | null]> = callerSpecifiesGit
+		? Object.entries(files)
+		: [[".git/HEAD", "ref: refs/heads/main\n"], ...Object.entries(files)];
+	for (const [relPath, contents] of entries) {
+		const abs = join(root, relPath);
+		mkdirSync(dirname(abs), { recursive: true });
+		if (contents !== null) {
+			writeFileSync(abs, contents, "utf-8");
+		} else {
+			mkdirSync(abs, { recursive: true });
+		}
+	}
+	return {
+		root,
+		cleanup: () => {
+			rmSync(root, { recursive: true, force: true });
+		},
+	};
+}

package/src/v1.ts

@@ -0,0 +1,32 @@
+/**
+ * `@neondatabase/env/v1` — resolve and inject Neon connection strings for the branch
+ * selected by your `neon.ts` policy.
+ *
+ * - `fetchEnv(config)` — async; resolves the branch + calls the Neon API for live
+ *   connection strings. Use in build scripts / top-level await.
+ * - `parseEnv(config)` — sync; reads already-injected `process.env` and validates it.
+ *   Use in app bootstrap (Drizzle config, Next.js, Vite, …).
+ * - `toEntries(env)` — project a resolved env into `{ KEY: value }` pairs.
+ *
+ * The branch policy type (`Config`) and `defineConfig` come from `@neondatabase/config`.
+ */
+
+export type {
+	FetchEnvOptions,
+	NeonAuthEnv,
+	NeonDataApiEnv,
+	NeonEnv,
+	NeonPostgresEnv,
+} from "./lib/env.js";
+export {
+	fetchEnv,
+	NEON_ENV_VAR_KEYS,
+	parseEnv,
+	toEntries,
+} from "./lib/env.js";
+
+// The branch policy type (`Config`) and `defineConfig` live in `@neondatabase/config`.
+// Import them from there directly:
+//   import { defineConfig } from "@neondatabase/config/v1";
+// They are intentionally not re-exported here to keep this package's surface focused on
+// env resolution and to avoid coupling the two packages' type-declaration bundles.

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"include": ["src", "e2e", "vitest.config.ts", "vitest.e2e.config.ts", "tsdown.config.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	name: "@neondatabase/env",
+	bundle: false,
+	clean: true,
+	dts: true,
+	entry: [
+		"src/index.ts",
+		"src/v1.ts",
+		"src/cli.ts",
+		"src/lib/**/*.ts",
+		"!src/**/*.test.*",
+		"!src/lib/fake-neon-api.ts",
+		"!src/lib/test-utils.ts",
+	],
+	format: "esm",
+	outDir: "dist",
+	treeshake: true,
+});

package/vitest.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		clearMocks: true,
+		mockReset: true,
+		unstubEnvs: true,
+		coverage: {
+			all: true,
+			include: ["src"],
+			exclude: ["src/**/*.test.ts"],
+			reporter: ["html", "lcov"],
+		},
+		// Skip e2e tests (which talk to the real Neon API) in the standard suite — they
+		// run via `pnpm test:e2e` against `vitest.e2e.config.ts`.
+		exclude: ["lib", "node_modules", "dist", "**/*.e2e.test.ts", "e2e/**"],
+		setupFiles: ["console-fail-test/setup"],
+	},
+});

package/vitest.e2e.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Vitest config for end-to-end tests that hit the **real** Neon API.
+ *
+ * - Matches `**\/*.e2e.test.ts` only — the standard `test:ci` config explicitly excludes
+ *   this pattern so the two suites never collide.
+ * - Uses long per-test timeouts because real project creation / deletion can take 10+s.
+ * - Forces single-threaded execution to avoid quota / rate-limit interference between
+ *   tests (`pool: "forks"` with `singleFork: true`).
+ * - Loads `.env` via Vitest's built-in dotenv support so `NEON_API_KEY` (and optionally
+ *   `NEON_ORG_ID`) become `process.env` entries inside the tests.
+ */
+export default defineConfig({
+	test: {
+		include: ["src/**/*.e2e.test.ts", "e2e/**/*.test.ts"],
+		exclude: ["node_modules", "dist"],
+		setupFiles: ["./e2e/load-env.ts", "./e2e/setup.ts"],
+		testTimeout: 120_000,
+		hookTimeout: 120_000,
+		pool: "forks",
+		poolOptions: {
+			forks: {
+				singleFork: true,
+			},
+		},
+		reporters: ["verbose"],
+	},
+});