Skip to content

refactor(12factor-env): centralize permissive env parsers#1372

Draft
Zetazzz wants to merge 1 commit into
refactor/env-ownershipfrom
refactor/shared-env-parsers
Draft

refactor(12factor-env): centralize permissive env parsers#1372
Zetazzz wants to merge 1 commit into
refactor/env-ownershipfrom
refactor/shared-env-parsers

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

This PR is stacked on #1371 and should initially be reviewed against refactor/env-ownership.

Summary

This PR moves the repository's shared permissive environment-value parsers into the neutral 12factor-env mechanism layer.

  • Adds parseEnvBoolean, parseEnvNumber, and parseEnvStringArray.
  • Exposes them from both the package root and the lightweight 12factor-env/parsers entry point.
  • Migrates PGPM, GraphQL, PostgreSQL, jobs, email-function, and SMTP test consumers.
  • Removes the generic parser re-exports from @pgpmjs/env.
  • Updates direct dependencies and workspace lockfile importers.

This changes parser ownership only. It does not move environment variables, defaults, configuration sections, output structures, or merge behavior between runtime packages.

Why

Several unrelated jobs and function packages depended on @pgpmjs/env only to reuse a generic boolean parser, while GraphQL and PostgreSQL packages maintained duplicate implementations.

12factor-env is the neutral lower-level package for environment parsing and validation mechanics, so it can provide these pure conversions without making PGPM or GraphQL env a general-purpose utility package.

Compatibility

The shared parsers intentionally preserve the existing permissive behavior:

  • parseEnvBoolean(undefined) returns undefined. Only true, 1, and yes are true, case-insensitively and without trimming; every other defined string is false.
  • parseEnvNumber() continues to use JavaScript Number() conversion and returns undefined only when the result is NaN.
  • parseEnvStringArray() continues to split on commas, trim entries, remove empty entries, and preserve ordering and duplicates.

The 12factor-env/parsers entry is pure: it does not read process.env, access files or secrets, or load envalid.

Existing envalid-backed strict validators and secret-file behavior remain unchanged. Parsers with different contracts remain local to their owners.

API impact

Consumers should import shared parsers from 12factor-env/parsers.

@pgpmjs/env no longer publicly re-exports parseEnvBoolean or parseEnvNumber.

This is an API relocation only; PGPM, GraphQL, jobs, and function runtimes continue to own their respective variable names, defaults, configuration structures, and fallback policies.

Package exports

12factor-env now declares explicit exports for:

  • the package root;
  • 12factor-env/parsers;
  • package.json;
  • previously usable root and ESM deep-entry paths.

Published-package smoke tests build the distributable package and verify root and parser imports through CommonJS and native ESM.

Validation

  • 12factor-env: 47 tests
  • PGPM env: 13 tests
  • GraphQL env: 10 tests
  • SMTP postmaster: 3 tests
  • Postmaster: 11 tests
  • All affected env, jobs, function, SMTP, and Postmaster packages build successfully.
  • Frozen-lockfile, package-resolution, formatting, and diff checks pass.

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.

1 participant