@neondatabase/env 0.0.0 → 0.1.0

package/src/lib/env.ts

@@ -1,610 +0,0 @@
-import {
-	type BranchConfig,
-	type Config,
-	createNeonApiFromOptions,
-	ErrorCode,
-	type NeonApi,
-	type NeonBranchSnapshot,
-	type NeonDatabaseSnapshot,
-	type NeonRoleSnapshot,
-	PlatformError,
-	resolveConfig,
-} from "@neondatabase/config/v1";
-import { z } from "zod";
-
-/**
- * Mapping between the {@link NeonEnv} property paths and the OS-level env-var keys used
- * for cross-process transport (via `.env` files, `env run -- <cmd>`, or anything else
- * that talks to `process.env`).
- *
- * Each top-level key here is a {@link NeonEnv} namespace; the inner record maps the
- * camelCase property names exposed to TypeScript to the UPPER_SNAKE env-var names used
- * by the OS. Keep this in sync with {@link postgresEnvSchema} / {@link authEnvSchema} /
- * {@link dataApiEnvSchema}.
- */
-export const NEON_ENV_VAR_KEYS = {
-	postgres: {
-		databaseUrl: "DATABASE_URL",
-		databaseUrlUnpooled: "DATABASE_URL_UNPOOLED",
-	},
-	auth: {
-		baseUrl: "NEON_AUTH_BASE_URL",
-	},
-	dataApi: {
-		url: "NEON_DATA_API_URL",
-	},
-} as const;
-
-/** Per-namespace inner shapes. Exposed so consumers can name the parts independently. */
-export interface NeonPostgresEnv {
-	/**
-	 * Pooled connection string (via Neon's PgBouncer pooler). The right default for
-	 * serverless drivers (`@neondatabase/serverless`, edge runtimes, Postgres.js, …).
-	 */
-	databaseUrl: string;
-	/**
-	 * Direct (unpooled) connection string. Use this when you need session-level
-	 * features (`LISTEN`/`NOTIFY`, prepared statements across calls, transactions
-	 * spanning round-trips) that PgBouncer's transaction-mode pooling drops.
-	 */
-	databaseUrlUnpooled: string;
-}
-
-/**
- * Bits of a Neon Auth integration for the resolved branch. Only present on `NeonEnv`
- * when the branch policy enables `auth`.
- *
- * Neon Auth exposes a single `baseUrl` that doubles as the publishable client identifier
- * — the rest of the surface (project id, JWKS URL, …) is derived from it at runtime by
- * the Neon Auth SDK. `fetchEnv` reads it from the live integration; `parseEnv` reads it
- * from `process.env` (`NEON_AUTH_BASE_URL`).
- */
-export interface NeonAuthEnv {
-	baseUrl: string;
-}
-
-/** Bits of a Neon Data API integration. Only present when the branch policy enables it. */
-export interface NeonDataApiEnv {
-	url: string;
-}
-
-/**
- * Empty record alias used as the "false" branch of the conditional namespace adds below.
- * `Record<never, never>` is the no-op for intersection — the cleaner alternative to `{}`,
- * which biome rejects (it means "any non-null", not "empty object").
- */
-type NoNamespace = Record<never, never>;
-
-type BranchConfigOf<C extends Config> = ReturnType<C> extends BranchConfig
-	? ReturnType<C>
-	: BranchConfig;
-
-type ServiceToggleOf<Cfg, Key extends "auth" | "dataApi"> = Cfg extends unknown
-	? Key extends keyof Cfg
-		? Cfg[Key]
-		: never
-	: never;
-
-type HasEnabledService<Cfg, Key extends "auth" | "dataApi"> = [
-	Exclude<ServiceToggleOf<Cfg, Key>, undefined | { enabled: false }>,
-] extends [never]
-	? false
-	: true;
-
-type IsDefaultConfig<C extends Config> = Config extends C ? true : false;
-
-/**
- * Static, namespaced shape of `fetchEnv` / `parseEnv`'s return value. Generic over the
- * {@link Config} so the type system knows which optional namespaces are present.
- *
- * - `postgres` is always present.
- * - `auth` is added iff the config return type has an `auth` namespace that is not
- *   explicitly disabled.
- * - `dataApi` is added iff the config return type has a `dataApi` namespace that is not
- *   explicitly disabled.
- */
-export type NeonEnv<C extends Config = Config> = {
-	postgres: NeonPostgresEnv;
-} & (IsDefaultConfig<C> extends true
-	? NoNamespace
-	: HasEnabledService<BranchConfigOf<C>, "auth"> extends true
-		? { auth: NeonAuthEnv }
-		: NoNamespace) &
-	(IsDefaultConfig<C> extends true
-		? NoNamespace
-		: HasEnabledService<BranchConfigOf<C>, "dataApi"> extends true
-			? { dataApi: NeonDataApiEnv }
-			: NoNamespace);
-
-export interface FetchEnvOptions {
-	/**
-	 * Neon project id. **Required** — the management API addresses branches through their
-	 * project. Resolve it in your CLI (e.g. neonctl) and pass it in.
-	 */
-	projectId: string;
-	/** Neon branch id (`br-…`). **Required.** Resolve names to ids before calling. */
-	branchId: string;
-	/**
-	 * Neon API key. Resolved via the standard chain (option → `NEON_API_KEY` →
-	 * `~/.config/neonctl/credentials.json`) when omitted. Ignored when a custom `api`
-	 * is supplied.
-	 */
-	apiKey?: string;
-	/**
-	 * Inject a custom NeonApi adapter. Primarily used by tests; production callers can rely
-	 * on the default real adapter built from `apiKey`.
-	 */
-	api?: NeonApi;
-	/**
-	 * Role name to fetch credentials for. When omitted, the only role on the branch is
-	 * auto-picked; throws {@link PlatformError} with `PLATFORM_AMBIGUOUS_BRANCH_AUTH` if
-	 * the branch has more than one role.
-	 */
-	roleName?: string;
-	/**
-	 * Database name. When omitted, the only database on the branch is auto-picked; throws
-	 * {@link PlatformError} with `PLATFORM_AMBIGUOUS_BRANCH_AUTH` if the branch has more
-	 * than one database.
-	 */
-	databaseName?: string;
-	/**
-	 * Env source used for one-time Auth keys that cannot be refetched after integration
-	 * creation. Defaults to `process.env`; callers may layer values from `.env.local`.
-	 */
-	env?: NodeJS.ProcessEnv;
-}
-
-/**
- * Resolve the project + branch this process should target, then fetch live Neon
- * connection strings for that branch over the network. Async — calls the Neon API.
- *
- * Use this from build scripts and the `neon-env run` command, where top-level await is
- * fine. For application code that needs a synchronous bootstrap (most frameworks: Drizzle
- * config, Next.js, Vite, etc.), inject env vars via `neon-env run -- <cmd>` and use
- * {@link parseEnv} instead — same {@link NeonEnv} shape, but a sync call against
- * `process.env`.
- *
- * Filesystem- and env-agnostic: pass `projectId` and the target `branchId` explicitly
- * (resolve them in your CLI, e.g. neonctl).
- *
- * ```ts
- * import config from "../neon";
- * import { fetchEnv } from "@neondatabase/env/v1";
- *
- * const env = await fetchEnv(config, { projectId: "patient-art-12345", branchId: "br-…" });
- * const db = drizzle(neon(env.postgres.databaseUrl), { schema });
- * ```
- *
- * The package does **not** mutate `process.env` or the filesystem itself.
- */
-export async function fetchEnv<const C extends Config>(
-	config: C,
-	options: FetchEnvOptions,
-): Promise<NeonEnv<C>> {
-	const api = options.api ?? createApiFromOptions(options);
-	const projectId = options.projectId;
-
-	const branches = await api.listBranches(projectId);
-	if (branches.length === 0) {
-		throw new PlatformError(
-			ErrorCode.BranchNotFound,
-			[
-				`fetchEnv: project ${projectId} has no branches.`,
-				"Deploy your neon.ts policy (or create a branch) first, or pick a different project id.",
-			].join(" "),
-			{ details: { projectId } },
-		);
-	}
-
-	const branch = resolveBranch(options.branchId, branches);
-	const desired = resolveConfig(config, {
-		name: branch.name,
-		id: branch.id,
-		exists: true,
-		...(branch.parentId ? { parentId: branch.parentId } : {}),
-		isDefault: branch.isDefault,
-		isProtected: branch.protected,
-		...(branch.expiresAt ? { expiresAt: branch.expiresAt } : {}),
-	});
-
-	const [roles, databases] = await Promise.all([
-		api.listBranchRoles(projectId, branch.id),
-		api.listBranchDatabases(projectId, branch.id),
-	]);
-
-	const roleName = pickRoleName(roles, branch, options.roleName);
-	const databaseName = pickDatabaseName(
-		databases,
-		branch,
-		roleName,
-		options.databaseName,
-	);
-
-	// Fan out: always fetch both Postgres URIs. Conditionally fetch auth + dataApi based
-	// on the branch policy. Auth key fields are only returned at integration creation time;
-	// for Better Auth they may legitimately be empty, so absence in the local env becomes
-	// empty string values while still emitting the required variable names.
-	const wantsAuth = desired.authEnabled;
-	const wantsDataApi = desired.dataApiEnabled;
-
-	const [pooled, unpooled, authSnapshot, dataApiSnapshot] = await Promise.all(
-		[
-			api.getConnectionUri(projectId, {
-				branchId: branch.id,
-				databaseName,
-				roleName,
-				pooled: true,
-			}),
-			api.getConnectionUri(projectId, {
-				branchId: branch.id,
-				databaseName,
-				roleName,
-				pooled: false,
-			}),
-			wantsAuth
-				? api.getNeonAuth(projectId, branch.id)
-				: Promise.resolve(null),
-			wantsDataApi
-				? api.getNeonDataApi(projectId, branch.id, databaseName)
-				: Promise.resolve(null),
-		],
-	);
-
-	const result: Record<string, unknown> = {
-		postgres: {
-			databaseUrl: pooled.uri,
-			databaseUrlUnpooled: unpooled.uri,
-		},
-	};
-
-	if (wantsAuth) {
-		if (!authSnapshot) {
-			throw new PlatformError(
-				ErrorCode.NotFound,
-				[
-					`fetchEnv: branch policy enables auth but no Neon Auth integration is enabled on branch ${branch.name} (${branch.id}).`,
-					"Enable it via `apply(config, { projectId, branchId })` (or `npx neonctl …`), in the Neon Console — then re-run fetchEnv. Or return auth.enabled=false.",
-				].join(" "),
-				{
-					details: { projectId, branchId: branch.id },
-				},
-			);
-		}
-		const baseUrl = resolveAuthBaseUrl(
-			authSnapshot.baseUrl,
-			options.env ?? process.env,
-		);
-		result.auth = { baseUrl } satisfies NeonAuthEnv;
-	}
-
-	if (wantsDataApi) {
-		if (!dataApiSnapshot) {
-			throw new PlatformError(
-				ErrorCode.NotFound,
-				[
-					`fetchEnv: branch policy enables dataApi but no Data API integration is enabled on branch ${branch.name} (${branch.id}) database ${databaseName}.`,
-					"Enable it via `apply(config, { projectId, branchId })` or in the Neon Console — then re-run fetchEnv. Or return dataApi.enabled=false.",
-				].join(" "),
-				{
-					details: {
-						projectId,
-						branchId: branch.id,
-						databaseName,
-					},
-				},
-			);
-		}
-		result.dataApi = { url: dataApiSnapshot.url } satisfies NeonDataApiEnv;
-	}
-
-	return result as NeonEnv<C>;
-}
-
-/**
- * Resolve the Neon Auth base URL to surface in `env.auth`. Prefer the value returned by
- * the integration (`getNeonAuth` includes it); fall back to whatever is already in the
- * caller's env source so older integrations created before `base_url` was returned still
- * round-trip through `env run`.
- */
-function resolveAuthBaseUrl(
-	snapshotBaseUrl: string | undefined,
-	source: NodeJS.ProcessEnv,
-): string {
-	if (snapshotBaseUrl && snapshotBaseUrl !== "") return snapshotBaseUrl;
-	return source[NEON_ENV_VAR_KEYS.auth.baseUrl] ?? "";
-}
-
-function createApiFromOptions(options: FetchEnvOptions): NeonApi {
-	return createNeonApiFromOptions(
-		"fetchEnv",
-		options.apiKey ? { apiKey: options.apiKey } : {},
-	);
-}
-
-function resolveBranch(
-	branchId: string,
-	branches: NeonBranchSnapshot[],
-): NeonBranchSnapshot {
-	const match = branches.find((b) => b.id === branchId);
-	if (match) return match;
-	throw new PlatformError(
-		ErrorCode.BranchNotFound,
-		[
-			`fetchEnv: branch id ${JSON.stringify(branchId)} not found on project.`,
-			`Existing branches: ${branches.map((b) => `${b.name} (${b.id})`).join(", ")}.`,
-		].join(" "),
-		{
-			details: {
-				branchId,
-				available: branches.map((b) => b.id),
-			},
-		},
-	);
-}
-
-function pickRoleName(
-	roles: NeonRoleSnapshot[],
-	branch: NeonBranchSnapshot,
-	requested: string | undefined,
-): string {
-	if (requested) {
-		if (!roles.some((r) => r.name === requested)) {
-			throw new PlatformError(
-				ErrorCode.BranchNotFound,
-				[
-					`fetchEnv: role "${requested}" not found on branch ${branch.name} (${branch.id}).`,
-					`Existing roles: ${roles.map((r) => r.name).join(", ") || "(none)"}.`,
-				].join(" "),
-				{
-					details: {
-						branchId: branch.id,
-						roleName: requested,
-						availableRoles: roles.map((r) => r.name),
-					},
-				},
-			);
-		}
-		return requested;
-	}
-	if (roles.length === 0) {
-		throw new PlatformError(
-			ErrorCode.BranchNotFound,
-			[
-				`fetchEnv: branch ${branch.name} (${branch.id}) has no roles.`,
-				"Create one via the Neon console or pass `roleName` explicitly.",
-			].join(" "),
-			{ details: { branchId: branch.id } },
-		);
-	}
-	if (roles.length === 1) return roles[0].name;
-	throw new PlatformError(
-		ErrorCode.AmbiguousBranchAuth,
-		[
-			`fetchEnv: branch ${branch.name} (${branch.id}) has ${roles.length} roles; cannot auto-pick.`,
-			`Pass \`roleName\` explicitly. Available: ${roles.map((r) => r.name).join(", ")}.`,
-		].join(" "),
-		{
-			details: {
-				branchId: branch.id,
-				availableRoles: roles.map((r) => r.name),
-			},
-		},
-	);
-}
-
-function pickDatabaseName(
-	databases: NeonDatabaseSnapshot[],
-	branch: NeonBranchSnapshot,
-	roleName: string,
-	requested: string | undefined,
-): string {
-	if (requested) {
-		if (!databases.some((d) => d.name === requested)) {
-			throw new PlatformError(
-				ErrorCode.BranchNotFound,
-				[
-					`fetchEnv: database "${requested}" not found on branch ${branch.name} (${branch.id}).`,
-					`Existing databases: ${databases.map((d) => d.name).join(", ") || "(none)"}.`,
-				].join(" "),
-				{
-					details: {
-						branchId: branch.id,
-						databaseName: requested,
-						availableDatabases: databases.map((d) => d.name),
-					},
-				},
-			);
-		}
-		return requested;
-	}
-	if (databases.length === 0) {
-		throw new PlatformError(
-			ErrorCode.BranchNotFound,
-			[
-				`fetchEnv: branch ${branch.name} (${branch.id}) has no databases.`,
-				"Create one via the Neon console or pass `databaseName` explicitly.",
-			].join(" "),
-			{ details: { branchId: branch.id } },
-		);
-	}
-	if (databases.length === 1) return databases[0].name;
-
-	// Prefer a database owned by the role we're connecting as.
-	const owned = databases.filter((d) => d.ownerName === roleName);
-	if (owned.length === 1) return owned[0].name;
-
-	throw new PlatformError(
-		ErrorCode.AmbiguousBranchAuth,
-		[
-			`fetchEnv: branch ${branch.name} (${branch.id}) has ${databases.length} databases; cannot auto-pick.`,
-			`Pass \`databaseName\` explicitly. Available: ${databases.map((d) => d.name).join(", ")}.`,
-		].join(" "),
-		{
-			details: {
-				branchId: branch.id,
-				availableDatabases: databases.map((d) => d.name),
-			},
-		},
-	);
-}
-
-// ───────────────────────── parseEnv ─────────────────────────
-
-/**
- * Per-namespace zod schemas. Each defines exactly the OS-level keys parsed from
- * `process.env` for its namespace. Keep in sync with {@link NEON_ENV_VAR_KEYS}.
- *
- * `z.string().url()` would be tighter than `min(1)` but Postgres URIs that include
- * URL-illegal characters in the password (rare but legal in Neon's connection-string
- * format) fail the WHATWG `URL` parse, so we settle for "non-empty string".
- */
-const postgresEnvSchema = z.object({
-	DATABASE_URL: z
-		.string({ message: "DATABASE_URL is missing" })
-		.min(1, "DATABASE_URL must not be empty"),
-	DATABASE_URL_UNPOOLED: z
-		.string({ message: "DATABASE_URL_UNPOOLED is missing" })
-		.min(1, "DATABASE_URL_UNPOOLED must not be empty"),
-});
-
-const authEnvSchema = z.object({
-	NEON_AUTH_BASE_URL: z
-		.string({ message: "NEON_AUTH_BASE_URL is missing" })
-		.min(1, "NEON_AUTH_BASE_URL must not be empty"),
-});
-
-const dataApiEnvSchema = z.object({
-	NEON_DATA_API_URL: z
-		.string({ message: "NEON_DATA_API_URL is missing" })
-		.min(1, "NEON_DATA_API_URL must not be empty"),
-});
-
-/**
- * Synchronous, network-free counterpart to {@link fetchEnv}. Reads `process.env` (or
- * `options.env`), validates the required Neon env vars with zod, and returns the same
- * {@link NeonEnv} shape — so the rest of your app touches `env.postgres.databaseUrl`
- * instead of stringly-typed `process.env.DATABASE_URL` lookups.
- *
- * Designed for the **"env-vars-already-injected"** path:
- * - You wrapped your dev command with `neon-env run -- <cmd>`.
- * - Your platform (Vercel, Fly, Railway, …) injected the vars via its own integration.
- *
- * Takes a branch **name** (not an id like the API-backed `fetchEnv` / config operations):
- * `parseEnv` makes no Neon API call, so the only thing it needs the branch for is
- * evaluating your `neon.ts` policy, which switches on `branch.name`. With no network round
- * trip there's no way to turn a `br-…` id into a name, so the name is passed directly.
- * Pass it explicitly so the result is deterministic and not coupled to any `NEON_*` env
- * var. (The `neon-env` CLI injects `NEON_BRANCH_NAME`; pass that through, or default to
- * your main branch name.) Prefer `fetchEnv` when runtime code needs the exact live branch.
- *
- * Throws `PlatformError(EnvNotInjected)` listing every missing/invalid var when the env
- * isn't fully populated, with a fix hint pointing back at `neon-env run`.
- *
- * ```ts
- * import config from "../neon";
- * import { parseEnv } from "@neondatabase/env/v1";
- *
- * const env = parseEnv(config, process.env.NEON_BRANCH_NAME ?? "main");
- * const db = drizzle(neon(env.postgres.databaseUrl), { schema });
- * // env.auth is statically typed when the config return type has auth: {} or auth.enabled: true.
- * ```
- */
-export function parseEnv<const C extends Config>(
-	config: C,
-	branchName: string,
-): NeonEnv<C> {
-	const source = process.env;
-	const issues: string[] = [];
-	const result: Record<string, unknown> = {};
-	const desired = resolveConfig(config, {
-		name: branchName,
-		exists: true,
-	});
-
-	const pg = postgresEnvSchema.safeParse({
-		DATABASE_URL: source.DATABASE_URL,
-		DATABASE_URL_UNPOOLED: source.DATABASE_URL_UNPOOLED,
-	});
-	if (pg.success) {
-		result.postgres = {
-			databaseUrl: pg.data.DATABASE_URL,
-			databaseUrlUnpooled: pg.data.DATABASE_URL_UNPOOLED,
-		} satisfies NeonPostgresEnv;
-	} else {
-		for (const issue of pg.error.issues) issues.push(issue.message);
-	}
-
-	if (desired.authEnabled) {
-		const auth = authEnvSchema.safeParse({
-			NEON_AUTH_BASE_URL: source.NEON_AUTH_BASE_URL,
-		});
-		if (auth.success) {
-			result.auth = {
-				baseUrl: auth.data.NEON_AUTH_BASE_URL,
-			} satisfies NeonAuthEnv;
-		} else {
-			for (const issue of auth.error.issues) issues.push(issue.message);
-		}
-	}
-
-	if (desired.dataApiEnabled) {
-		const dataApi = dataApiEnvSchema.safeParse({
-			NEON_DATA_API_URL: source.NEON_DATA_API_URL,
-		});
-		if (dataApi.success) {
-			result.dataApi = {
-				url: dataApi.data.NEON_DATA_API_URL,
-			} satisfies NeonDataApiEnv;
-		} else {
-			for (const issue of dataApi.error.issues)
-				issues.push(issue.message);
-		}
-	}
-
-	if (issues.length > 0) {
-		throw new PlatformError(
-			ErrorCode.EnvNotInjected,
-			[
-				"parseEnv: the required Neon env variables are not present in process.env.",
-				...issues.map((i) => `  - ${i}`),
-				"Inject them via one of:",
-				"  - `neon-env run -- <your dev command>` (wraps the command with the vars injected)",
-				"  - your hosting platform's Neon integration (Vercel, Fly, Railway, …)",
-				"Or switch the call to `await fetchEnv(config)` if you're in a context that can do async I/O.",
-			].join("\n"),
-			{ details: { missing: issues } },
-		);
-	}
-
-	return result as NeonEnv<C>;
-}
-
-// ───────────────────────── env-var mapping helpers ─────────────────────────
-
-/**
- * Project a fully-resolved {@link NeonEnv} into the OS-level `{ KEY: value }` pairs used
- * for cross-process transport. Named after the web-platform `.entries()` convention
- * (`URLSearchParams` / `Headers` / `FormData`); returns a `Record` rather than an
- * iterator of tuples since that's the shape env injection needs (wrap with
- * `Object.entries(...)` if you want literal `[key, value]` pairs). Used by `neon-env run`
- * to inject the vars into a subprocess's `process.env`.
- *
- * Walks the value at runtime so it works for any `NeonEnv<C>` regardless of which
- * conditional namespaces are present.
- */
-export function toEntries(env: NeonEnv<Config>): Record<string, string> {
-	const out: Record<string, string> = {
-		[NEON_ENV_VAR_KEYS.postgres.databaseUrl]: env.postgres.databaseUrl,
-		[NEON_ENV_VAR_KEYS.postgres.databaseUrlUnpooled]:
-			env.postgres.databaseUrlUnpooled,
-	};
-	const withAuth = env as { auth?: NeonAuthEnv };
-	if (withAuth.auth) {
-		out[NEON_ENV_VAR_KEYS.auth.baseUrl] = withAuth.auth.baseUrl;
-	}
-	const withDataApi = env as { dataApi?: NeonDataApiEnv };
-	if (withDataApi.dataApi) {
-		out[NEON_ENV_VAR_KEYS.dataApi.url] = withDataApi.dataApi.url;
-	}
-	return out;
-}