Skip to content

feat: add warning spec attribute - #257

Open
vergiLgood1 wants to merge 1 commit into
af:mainfrom
vergiLgood1:feat/warning-option
Open

vergiLgood1 wants to merge 1 commit into
af:mainfrom
vergiLgood1:feat/warning-option

Conversation

@vergiLgood1

Copy link
Copy Markdown

Summary

Adds an optional warning message to validator specs. When an env var is not set and a fallback value (default, devDefault, or testDefault) is used, the message is surfaced by the reporter without failing the program.

Closes #220

Design decision

The issue's example uses str({ warning: "..." }) with no default and implies the app should keep running ("App will run but it will not send any email"). However, making warning implicitly turn a required var into an optional one would conflict with the library's philosophy (a program should only run when its environment dependencies are met) and could silently weaken validation — e.g. someone adding a warning message to a required database password var.

So this PR keeps optionality explicit, consistent with how default: undefined already works:

const env = cleanEnv(process.env, {
  EMAIL_SMTP: str({
    default: undefined,
    warning: 'EMAIL_SMTP is not set. App will run but it will not send any email.',
  }),
})
// Program runs, value is undefined, and the warning is logged.

With a concrete fallback, the warning fires when that fallback is used:

const env = cleanEnv(process.env, {
  RETRIES: str({ default: '3', warning: 'RETRIES not set, using default 3' }),
})

I'm happy to adjust if a different behavior (e.g. warning implying optionality) is preferred.

Changes

  • src/types.ts — new warning?: string on Spec<T>; new optional warnings field on ReporterOptions<T>
  • src/core.ts — getSanitizedEnv records a warning whenever the env var was not set and a fallback (testDefault / devDefault / default) was used, and passes warnings to the reporter. With reporter: null the caller opts out of all reporting, including warnings (errors are still thrown, as before)
  • src/reporter.ts — defaultReporter prints a Warnings: section (same visual style as the error sections). Warnings never affect the exit behavior: with only warnings the process exits normally; with errors the existing error/exit flow is unchanged
  • README.md — documents the new attribute
  • tests/warning.test.ts — new: warning recorded for default / devDefault / testDefault fallbacks, no warning when the var is set, missing var without any fallback still errors, reporter: null behavior, and type-level assertions (optionality still driven by default: undefined, not by warning)
  • tests/reporter.test.ts — new: warnings printed without exiting, warnings + errors printed together with exit preserved, warnings sorted
  • tests/requiredWhen.test.ts — updated to match the new reporter call signature (warnings: {})

Verification

  • bun run ts ✅
  • bun run lint ✅
  • bun run test:ci ✅ (82 tests, 8 files)
  • bun run coverage ✅ (functions 100%, lines 98.89% — above the 98% thresholds)

Example output:

 =================================
  Warnings:
     EMAIL_SMTP: EMAIL_SMTP is not set. App will run but it will not send any email.
 =================================

Logs an optional warning message (without failing) whenever an env var
is not set and a fallback value (default/devDefault/testDefault) is used.
Closes af#220
@af

af commented Oct 31, 2026

Copy link
Copy Markdown
Owner

I asked Claude to do a triage review of this and it found a few problems. I verified the first one which seems like a regression, can you take a look?

The review of PR #257 found eight issues. The first one should block the merge: with reporter: null, requiredWhen errors are now silently
  dropped. Those errors are collected but never thrown, so when the reporter is skipped they disappear. Before this PR, the default reporter
  still caught them.

  The other two bugs:
  - Missing logger crash: the new warnings code calls logger(...) without the default-logger fallback the error path has. A reporter set up
    without a logger now crashes on the first warning.
  - Conflicting messages: one variable can appear under both "Warnings" and "Missing" when its requiredWhen check fails.

  The rest are design, docs and cleanup notes:
  - Error handling also changed: the reporter: null special case affects errors as well as warnings. Turning off only the warnings would leave
    error handling as it was.
  - Dev and test noise: warnings also fire for devDefault and testDefault, so every dev and test run prints them.
  - README not updated: it doesn't mention the new warnings field, so custom reporters drop warnings without saying why.
  - Same output as errors: warnings go to the same output as errors, with no separate setting to redirect or silence them.
  - Duplicated formatting: the warnings formatting repeats the error formatting code; a small shared helper would remove the copy.

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.

Add a warn option

2 participants