From afd125fc12ac6a9b3163f28d8f0f4e5d809eb820 Mon Sep 17 00:00:00 2001 From: robobun Date: Fri, 24 Oct 2025 14:43:05 -0700 Subject: [PATCH] docs(env_var): document silent error handling behavior (#24043) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ### What does this PR do? This PR adds documentation comments to `src/env_var.zig` that explain the silent error handling behavior for environment variable deserialization, based on the documentation from the closed PR #24036. The comments clarify: 1. **Module-level documentation**: Environment variables may fail to parse silently. When they do, the default behavior is to show a debug warning and treat them as not set. This is intentional to avoid panics from environment variable pollution. 2. **Inline documentation**: Deserialization errors cannot panic. Users needing more robust configuration mechanisms should consider alternatives to environment variables. This documentation complements the behavior change introduced in commit 0dd6aa47ea which replaced panic with debug_warn. ### How did you verify your code works? Ran `bun bd` successfully - the build completed without errors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Bot Co-authored-by: Claude --- src/env_var.zig | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/env_var.zig b/src/env_var.zig index 49d034f755..cdd75eda12 100644 --- a/src/env_var.zig +++ b/src/env_var.zig @@ -8,6 +8,12 @@ //! If default values are provided, the .get() method is guaranteed not to return a nullable type, //! whereas if no default is provided, the .get() method will return an optional type. //! +//! Note that environment variables may fail to parse silently. If they do fail to parse, the +//! default is to show a debug warning and treat them as not set. This behavior can be customized, +//! but environment variables are not meant to be a robust configuration mechanism. If you do think +//! your feature needs more customization, consider using other means. The reason we have decided +//! upon this behavior is to avoid panics due to environment variable pollution. +//! //! TODO(markovejnovic): It would be neat if this library supported loading floats as //! well as strings, integers and booleans, but for now this will do. //! @@ -341,6 +347,9 @@ const kind = struct { default: ?ValueType = null, deser: struct { /// Control how deserializing and deserialization errors are handled. + /// + /// Note that deserialization errors cannot panic. If you need more robust means of + /// handling inputs, consider not using environment variables. error_handling: enum { /// debug_warn on deserialization errors. debug_warn,