@neondatabase/env 0.0.0 → 0.1.1

package/dist/lib/env.d.ts

@@ -0,0 +1,194 @@
+import { BranchConfig, Config } from "../config/dist/lib/types.js";
+import { NeonApi } from "../config/dist/lib/neon-api.js";
+import "../config/dist/v1.js";
+
+//#region src/lib/env.d.ts
+
+/**
+ * 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}.
+ */
+declare const NEON_ENV_VAR_KEYS: {
+  readonly postgres: {
+    readonly databaseUrl: "DATABASE_URL";
+    readonly databaseUrlUnpooled: "DATABASE_URL_UNPOOLED";
+  };
+  readonly auth: {
+    readonly baseUrl: "NEON_AUTH_BASE_URL";
+  };
+  readonly dataApi: {
+    readonly url: "NEON_DATA_API_URL";
+  };
+};
+/** Per-namespace inner shapes. Exposed so consumers can name the parts independently. */
+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`).
+ */
+interface NeonAuthEnv {
+  baseUrl: string;
+}
+/** Bits of a Neon Data API integration. Only present when the branch policy enables it. */
+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.
+ */
+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);
+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.
+ */
+declare function fetchEnv<const C extends Config>(config: C, options: FetchEnvOptions): Promise<NeonEnv<C>>;
+/**
+ * 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.
+ * ```
+ */
+declare function parseEnv<const C extends Config>(config: C, branchName: string): NeonEnv<C>;
+/**
+ * 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.
+ */
+declare function toEntries(env: NeonEnv<Config>): Record<string, string>;
+//#endregion
+export { FetchEnvOptions, NEON_ENV_VAR_KEYS, NeonAuthEnv, NeonDataApiEnv, NeonEnv, NeonPostgresEnv, fetchEnv, parseEnv, toEntries };
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","names":[],"sources":["../../src/lib/env.ts"],"mappings":";;;;;;;;;;AAwBA;AAcA;AAuBA;AAKA;AAEC;AAOwB;AAEN,cArDN,iBAqDM,EAAA;WAAW,QAAA,EAAA;IAAqB,SAAA,WAAA,EAAA,cAAA;IAAX,SAAA,mBAAA,EAAA,uBAAA;;WAC1B,IAAA,EAAA;IAAX,SAAA,OAAA,EAAA,oBAAA;;EACY,SAAA,OAAA,EAAA;IAEV,SAAA,GAAA,EAAe,mBAAA;EAAA,CAAA;;;AACC,UA5CJ,eAAA,CA4CI;;;AACV;AAAA;EAIW,WAAA,EAAA,MAAA;;;;;AACd;EAKH,mBAAe,EAAA,MAAA;;;;;AAAqC;AAYzD;;;;;AAEqB,UA9CJ,WAAA,CA8CI;SAAhB,EAAA,MAAA;;;AAEgB,UA3CJ,cAAA,CA2CI;KAAlB,EAAA,MAAA;;;;;;;KAlCE,WAAA,GAAc,MAuCG,CAAA,KAAA,EAAA,KAAA,CAAA;KArCjB,cAqCD,CAAA,UArC0B,MAqC1B,CAAA,GArCoC,UAqCpC,CArC+C,CAqC/C,CAAA,SArC0D,YAqC1D,GApCD,UAoCC,CApCU,CAoCV,CAAA,GAnCD,YAmCC;KAjCC,eAkCW,CAAA,GAAA,EAAA,YAAA,MAAA,GAAA,SAAA,CAAA,GAlC4C,GAkC5C,SAAA,OAAA,GAjCb,GAiCa,SAAA,MAjCK,GAiCL,GAhCZ,GAgCY,CAhCR,GAgCQ,CAAA,GAAA,KAAA,GAAA,KAAA;KA5BX,iBA6BA,CAAA,GAAA,EAAA,YAAA,MAAA,GAAA,SAAA,CAAA,GAAA,CA5BJ,OA4Be,CA5BP,eA4BO,CA5BS,GA4BT,EA5Bc,GA4Bd,CAAA,EAAA,SAAA,GAAA;EAEC,OAAA,EAAA,KAAe;AAAA,CAAA,CAAA,UAkBzB,CAAA,KAAA,CAAA,GAAA,KAAA,GAAA,IAAA;KA3CF,eA4DS,CAAA,UA5DiB,MA4DjB,CAAA,GA5D2B,MA4D3B,SA5D0C,CA4D1C,GAAA,IAAA,GAAA,KAAA;AAAU;AA0BxB;;;;;;;;AAGU;AAyUM,KAtZJ,OAsZY,CAAA,UAtZM,MAsZN,GAtZe,MAsZf,CAAA,GAAA;EAAA,QAAA,EArZb,eAqZa;KApZnB,eAoZoC,CApZpB,CAoZoB,CAAA,SAAA,IAAA,GAnZtC,WAmZsC,GAlZtC,iBAkZsC,CAlZpB,cAkZoB,CAlZL,CAkZK,CAAA,EAAA,MAAA,CAAA,SAAA,IAAA,GAAA;MAChC,EAlZG,WAkZH;IAjZL,WAmZO,CAAA,GAAA,CAlZT,eAkZS,CAlZO,CAkZP,CAAA,SAAA,IAAA,GAjZP,WAiZO,GAhZP,iBAgZO,CAhZW,cAgZX,CAhZ0B,CAgZ1B,CAAA,EAAA,SAAA,CAAA,SAAA,IAAA,GAAA;SAAR,EA/Ya,cA+Yb;AAAO,CAAA,GA9YL,WA8YK,CAAA;AAgFM,UA5dC,eAAA,CA4dQ;EAAA;;;;EAA8B,SAAA,EAAA,MAAA;;;;;;;;;;;;;QA1chD;;;;;;;;;;;;;;;;;QAiBA,MAAA,CAAO;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BQ,yBAAyB,gBACtC,YACC,kBACP,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyUH,yBAAyB,gBAChC,wBAEN,QAAQ;;;;;;;;;;;;iBAgFK,SAAA,MAAe,QAAQ,UAAU"}

package/dist/lib/env.js

@@ -0,0 +1,263 @@
+import { ErrorCode, PlatformError, createNeonApiFromOptions, resolveConfig } from "@neondatabase/config/v1";
+import { z } from "zod";
+//#region src/lib/env.ts
+/**
+* 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}.
+*/
+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" }
+};
+/**
+* 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.
+*/
+async function fetchEnv(config, options) {
+	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);
+	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 = { 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
+		} });
+		result.auth = { baseUrl: resolveAuthBaseUrl(authSnapshot.baseUrl, options.env ?? process.env) };
+	}
+	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 };
+	}
+	return result;
+}
+/**
+* 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, source) {
+	if (snapshotBaseUrl && snapshotBaseUrl !== "") return snapshotBaseUrl;
+	return source[NEON_ENV_VAR_KEYS.auth.baseUrl] ?? "";
+}
+function createApiFromOptions(options) {
+	return createNeonApiFromOptions("fetchEnv", options.apiKey ? { apiKey: options.apiKey } : {});
+}
+function resolveBranch(branchId, branches) {
+	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, branch, requested) {
+	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, branch, roleName, requested) {
+	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;
+	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)
+	} });
+}
+/**
+* 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.
+* ```
+*/
+function parseEnv(config, branchName) {
+	const source = process.env;
+	const issues = [];
+	const result = {};
+	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
+	};
+	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 };
+		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 };
+		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;
+}
+/**
+* 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.
+*/
+function toEntries(env) {
+	const out = {
+		[NEON_ENV_VAR_KEYS.postgres.databaseUrl]: env.postgres.databaseUrl,
+		[NEON_ENV_VAR_KEYS.postgres.databaseUrlUnpooled]: env.postgres.databaseUrlUnpooled
+	};
+	const withAuth = env;
+	if (withAuth.auth) out[NEON_ENV_VAR_KEYS.auth.baseUrl] = withAuth.auth.baseUrl;
+	const withDataApi = env;
+	if (withDataApi.dataApi) out[NEON_ENV_VAR_KEYS.dataApi.url] = withDataApi.dataApi.url;
+	return out;
+}
+//#endregion
+export { NEON_ENV_VAR_KEYS, fetchEnv, parseEnv, toEntries };
+
+//# sourceMappingURL=env.js.map

package/dist/lib/env.js.map

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

package/dist/v1.d.ts

@@ -0,0 +1,2 @@
+import { FetchEnvOptions, NEON_ENV_VAR_KEYS, NeonAuthEnv, NeonDataApiEnv, NeonEnv, NeonPostgresEnv, fetchEnv, parseEnv, toEntries } from "./lib/env.js";
+export { type FetchEnvOptions, NEON_ENV_VAR_KEYS, type NeonAuthEnv, type NeonDataApiEnv, type NeonEnv, type NeonPostgresEnv, fetchEnv, parseEnv, toEntries };

package/dist/v1.js

@@ -0,0 +1,2 @@
+import { NEON_ENV_VAR_KEYS, fetchEnv, parseEnv, toEntries } from "./lib/env.js";
+export { NEON_ENV_VAR_KEYS, fetchEnv, parseEnv, toEntries };

package/package.json

@@ -1,22 +1,73 @@
 {
-	"name": "@neondatabase/env",
-	"version": "0.0.0",
-	"description": "Resolve and inject Neon connection strings for the branch selected by your neon.ts policy. fetchEnv / parseEnv plus a single `env run -- <cmd>` CLI.",
-	"keywords": [
-		"neon",
-		"database",
-		"postgres",
-		"env",
-		"dotenv",
-		"platform"
-	],
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/neondatabase/neon-pkgs.git"
-	},
-	"license": "Apache-2.0",
-	"author": {
-		"name": "Neon",
-		"url": "https://neon.com"
-	}
-}
+  "name": "@neondatabase/env",
+  "version": "0.1.1",
+  "description": "Resolve and inject Neon connection strings for the branch selected by your neon.ts policy. fetchEnv / parseEnv plus a single `env run -- <cmd>` CLI.",
+  "keywords": [
+    "neon",
+    "database",
+    "postgres",
+    "env",
+    "dotenv",
+    "platform"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neondatabase/neon-pkgs.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Neon",
+    "url": "https://neon.com"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "neon-env": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./v1": {
+      "types": "./dist/v1.d.ts",
+      "import": "./dist/v1.js",
+      "default": "./dist/v1.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "dist/",
+    "package.json"
+  ],
+  "devDependencies": {
+    "@neondatabase/api-client": "^2.7.1",
+    "@types/node": "^20.19.0",
+    "@types/yargs": "^17.0.35",
+    "@vitest/coverage-v8": "3.0.9",
+    "console-fail-test": "0.5.0",
+    "tsdown": "^0.14.1",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "yargs": "^18.0.0",
+    "@neondatabase/config": "0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsdown",
+    "test": "vitest --passWithNoTests",
+    "test:ci": "vitest run --passWithNoTests",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "tsc": "tsc"
+  }
+}

package/.env.example

@@ -1,5 +0,0 @@
-# Copy to `.env` and fill in real values. `.env` itself is gitignored.
-# Required to run `pnpm --filter @neondatabase/env test:e2e`.
-NEON_API_KEY=
-# Optional. When set, e2e tests scope project creation/listing to this org.
-NEON_ORG_ID=