Skip to content

feat(env): add optional key filter to parseEnv#211

Merged
andrelandgraf merged 1 commit into
mainfrom
feat/env-parseenv-key-filter
Jun 14, 2026
Merged

feat(env): add optional key filter to parseEnv#211
andrelandgraf merged 1 commit into
mainfrom
feat/env-parseenv-key-filter

Conversation

@andrelandgraf

Copy link
Copy Markdown
Collaborator

Summary

  • Adds a third way to call 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.
  • Use case: a process that only uses a subset (e.g. a Next.js app reading DATABASE_URL but not DATABASE_URL_UNPOOLED) no longer throws over vars it never uses.
  • The keys are typesafe via SelectableEnvKey<Config> — autocomplete only offers vars the policy enables, and selecting one from a disabled namespace is a compile error.
  • The result type (FilteredNeonEnv<K>) is narrowed: it drops unselected namespaces and unselected properties within a kept namespace (selecting ["DATABASE_URL"] yields { postgres: { databaseUrl: string } }).
  • Composes with the existing overloads — an array is unambiguous vs. the function-slug string at 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 / FilteredNeonEnv types + parseFilteredEnv runtime + FILTERABLE_ENV_KEYS reverse map.
  • src/v1.ts: export SelectableEnvKey and FilteredNeonEnv.
  • src/lib/env.test-d.ts (new): Vitest expectTypeOf type tests (positive equalities + @ts-expect-error negatives), plus a test:types script.
  • 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 tsc clean
  • pnpm --filter @neondatabase/env test:ci (63 tests)
  • pnpm --filter @neondatabase/env test:types (12 type tests, no type errors)
  • pnpm --filter @neondatabase/env build — verified dist/ excludes test-d and expect-type

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.
@andrelandgraf andrelandgraf enabled auto-merge (squash) June 14, 2026 16:18
@andrelandgraf andrelandgraf merged commit c6a00b7 into main Jun 14, 2026
10 checks passed
@andrelandgraf andrelandgraf deleted the feat/env-parseenv-key-filter branch June 14, 2026 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants