Clarify environment overrides and cover their edge cases

Document that an invalid per-event name does not fall back to the
default, move the README guidance into the configuration section, test
clearing an override, trimming control whitespace, and omitting an
unset environment, and apply the lint rules from main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ejsmith

.agents/skills/exceptionless-javascript/references/configuration.md

@@ -31,7 +31,7 @@ await Exceptionless.startup((config) => {
 
 ## Deployment environment
 
-Set `config.environment = "production"` or call `config.setEnvironment("production")`. Per-event `setEnvironment("staging")` overrides the default. Names are trimmed and retain their supplied casing; empty names, names longer than 64 characters, and control characters are ignored. Missing values remain unspecified. The server filters case-insensitively and normalizes aggregation keys. This property is independent of `data.@environment` runtime metadata and of the application version. It does not change server stack grouping or create per-environment status.
+Set `config.environment = "production"` or call `config.setEnvironment("production")`. Per-event `setEnvironment("staging")` overrides the default. Names are trimmed and retain their supplied casing; empty names, names longer than 64 characters, and names with control characters are unspecified. An invalid per-event name stays unspecified instead of using the default; pass `null` or `undefined` to `setEnvironment` to use the default. Missing values remain unspecified. The server filters case-insensitively and normalizes aggregation keys. This property is independent of `data.@environment` runtime metadata and of the application version. It does not change server stack grouping or create per-environment status.
 
 ## Privacy
 

README.md

@@ -8,8 +8,6 @@ The definition of the word exceptionless is: to be without exception. Exceptionl
 
 ## Browser
 
-Set a deployment environment in startup configuration with `config.environment = "production"` (or `config.setEnvironment("production")`). Override it on an event with `Exceptionless.createLog("Example").setEnvironment("staging").submit()`. Names are trimmed and limited to 64 characters, preserving the supplied casing. The server filters case-insensitively and normalizes aggregation keys. Missing or invalid names remain unspecified. The top-level `environment` is separate from machine/runtime diagnostics in `data.@environment`; stacks and fixed versions remain shared across environments.
-
 You can install the npm package via `npm install @exceptionless/browser --save`
 or via cdn [`https://unpkg.com/@exceptionless/browser`](https://unpkg.com/@exceptionless/browser).
 Next, you just need to call startup during your app's startup to automatically
@@ -158,6 +156,10 @@ await Exceptionless.startup((c) => {
 Please see the [docs](https://exceptionless.com/docs/clients/javascript/) for
 more information on configuring the client.
 
+#### Deployment environments
+
+Set a deployment environment in startup configuration with `config.environment = "production"` (or `config.setEnvironment("production")`). Override it on an event with `Exceptionless.createLog("Example").setEnvironment("staging").submit()`. Names are trimmed and limited to 64 characters, preserving the supplied casing. The server filters case-insensitively and normalizes aggregation keys. Missing or invalid names remain unspecified, and an invalid per-event name does not fall back to the configured default; pass `null` or `undefined` to `setEnvironment` to use the default. The top-level `environment` is separate from machine/runtime diagnostics in `data.@environment`; stacks and fixed versions remain shared across environments.
+
 ### Submitting Events and Errors
 
 Once configured, Exceptionless will automatically submit any unhandled exceptions

packages/core/src/EventBuilder.ts

@@ -7,15 +7,6 @@ import { isEmpty, stringify } from "./Utils.js";
 import { EventPluginContext } from "./plugins/EventPluginContext.js";
 
 export class EventBuilder {
-  public setEnvironment(value: string | null | undefined): EventBuilder {
-    if (value != null) {
-      this.target.environment = value;
-    } else {
-      delete this.target.environment;
-    }
-    return this;
-  }
-
   public target: Event;
   public client: ExceptionlessClient;
   public context: EventContext;
@@ -71,6 +62,15 @@ export class EventBuilder {
     return this;
   }
 
+  public setEnvironment(value: string | null | undefined): EventBuilder {
+    if (value != null) {
+      this.target.environment = value;
+    } else {
+      delete this.target.environment;
+    }
+    return this;
+  }
+
   public setMessage(message: string | null | undefined): EventBuilder {
     if (message) {
       this.target.message = message;

packages/core/test/configuration/Configuration.test.ts

@@ -18,6 +18,8 @@ describe("Configuration", () => {
     expect(config.environment).toBeUndefined();
     config.setEnvironment("prod\ninvalid");
     expect(config.environment).toBeUndefined();
+    config.setEnvironment("\tProduction\n");
+    expect(config.environment).toBe("Production");
   });
 
   test("should override configuration defaults", () => {

packages/core/test/plugins/default/ConfigurationDefaultsPlugin.test.ts

@@ -12,7 +12,14 @@ describe("ConfigurationDefaultsPlugin", () => {
     client.config.setEnvironment(" Production ");
     const plugin = new ConfigurationDefaultsPlugin();
     for (const type of ["error", "log", "usage", "session"]) {
-      const event: Event = { type, data: { "@environment": { machine_name: "worker-1" } } };
+      const event: Event = {
+        type,
+        data: {
+          "@environment": {
+            machine_name: "worker-1"
+          }
+        }
+      };
       await plugin.run(new EventPluginContext(client, event, new EventContext()));
       expect(event.environment).toBe("Production");
       expect(event.data?.["@environment"]?.machine_name).toBe("worker-1");
@@ -32,6 +39,30 @@ describe("ConfigurationDefaultsPlugin", () => {
     expect(builder.target.environment).toBeUndefined();
   });
 
+  test.each([null, undefined])("should apply the default when the override is cleared with %j", async (environment) => {
+    const client = new ExceptionlessClient();
+    client.config.environment = "production";
+    const builder = client.createLog("test", "message").setEnvironment("staging").setEnvironment(environment);
+    await new ConfigurationDefaultsPlugin().run(new EventPluginContext(client, builder.target, new EventContext()));
+    expect(builder.target.environment).toBe("production");
+  });
+
+  test("should trim surrounding control whitespace from an override", async () => {
+    const client = new ExceptionlessClient();
+    client.config.environment = "production";
+    const builder = client.createLog("test", "message").setEnvironment("\tStaging\n");
+    await new ConfigurationDefaultsPlugin().run(new EventPluginContext(client, builder.target, new EventContext()));
+    expect(builder.target.environment).toBe("Staging");
+  });
+
+  test("should omit an unspecified environment from the serialized event", async () => {
+    const client = new ExceptionlessClient();
+    const builder = client.createLog("test", "message");
+    await new ConfigurationDefaultsPlugin().run(new EventPluginContext(client, builder.target, new EventContext()));
+    const serialized = JSON.parse(JSON.stringify(builder.target)) as Record<string, unknown>;
+    expect(Object.keys(serialized)).not.toContain("environment");
+  });
+
   describe("should add default", () => {
     const userDataKey: string = "user";
     const user = {

packages/core/test/plugins/default/DuplicateCheckerPlugin.test.ts

@@ -68,7 +68,9 @@ describe("DuplicateCheckerPlugin", () => {
       new EventContext()
     );
 
-    if (environment) context.event.environment = environment;
+    if (environment) {
+      context.event.environment = environment;
+    }
     await plugin.run(context);
     return context;
   };