feat(env): add optional key filter to parseEnv#211
Merged
Conversation
parseEnv(config, keys) accepts an array of OS-level env-var keys (e.g. ["DATABASE_URL", "NEON_AUTH_BASE_URL"]) as an alternative to the function-slug scope. Only the selected vars are enforced and returned, projected into a narrowed NeonEnv shape, so a process that uses only a subset (e.g. a Next.js app reading DATABASE_URL but not DATABASE_URL_UNPOOLED) no longer throws over vars it never uses. Keys are typesafe against the policy (SelectableEnvKey<Config>): selecting a var from a namespace the policy doesn't enable is a compile error, and the result type drops unselected namespaces and properties. Adds Vitest type tests (env.test-d.ts) plus a test:types script, runtime tests, README docs, and excludes *.test-d.* from the published bundle.
guillaumervls
approved these changes
Jun 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
parseEnv: a typesafe key filter.parseEnv(config, ["DATABASE_URL", ...])requires and returns only the selected OS-level env vars, instead of every variable the policy implies.DATABASE_URLbut notDATABASE_URL_UNPOOLED) no longer throws over vars it never uses.SelectableEnvKey<Config>— autocomplete only offers vars the policy enables, and selecting one from a disabled namespace is a compile error.FilteredNeonEnv<K>) is narrowed: it drops unselected namespaces and unselected properties within a kept namespace (selecting["DATABASE_URL"]yields{ postgres: { databaseUrl: string } }).stringat both runtime (Array.isArray) and the type level. Filter and function-slug scope remain separate, mutually-exclusive overloads.Changes
src/lib/env.ts: new overload +SelectableEnvKey/FilteredNeonEnvtypes +parseFilteredEnvruntime +FILTERABLE_ENV_KEYSreverse map.src/v1.ts: exportSelectableEnvKeyandFilteredNeonEnv.src/lib/env.test-d.ts(new): VitestexpectTypeOftype tests (positive equalities +@ts-expect-errornegatives), plus atest:typesscript.src/lib/env.test.ts: runtime tests for the filter.tsdown.config.ts: exclude*.test-d.*from the published bundle.README.md+ changeset (minor).Test plan
pnpm --filter @neondatabase/env tsccleanpnpm --filter @neondatabase/env test:ci(63 tests)pnpm --filter @neondatabase/env test:types(12 type tests, no type errors)pnpm --filter @neondatabase/env build— verifieddist/excludestest-dandexpect-type