fix(env-options): review suggestions

packages/env-options/README.md

@@ -64,9 +64,9 @@ const DEBUG_VALUES = getEnvironmentOptionsList('DEBUG');
 const DEBUG_AGORIC = environmentOptionsListHas('DEBUG', 'agoric');
 ```
 
-Another common Unix convention is for the value of an option to be a
+Another common convention is for the value of an option to be a
 comma (`','`) separated list of strings. `getEnvironmentOptionsList` will
-return this list, or an empty list of the option is absent.
+return this list, or an empty list if the option is absent.
 `environmentOptionsListHas` will test if this list contains a specific
 value, or return false if the option is absent.
 
@@ -79,9 +79,10 @@ than comma. Once these are fixed, then these uses can be switched to use
 
 The `'@endo/env-options'` module also exports a lower-level
 `makeEnvironmentCaptor` that you can apply to whatever object you wish to treat
-as a global, such as the global of another compartment. It returns an entagled
+as a global(having a "process" property with its own "env" record),
+such as the global of another compartment. It returns an entagled
 pair of a `getEnvironmentOption` function as above, and a
-`getCapturedEnvironmentOptionNames` function for that returns an array of
+`getCapturedEnvironmentOptionNames` function that returns an array of
 the option names used by that `getEnvironmentOption` function. This is
 useful to give feedback about
 which environment variables were actually read, for diagnostic purposes.

packages/env-options/src/env-options.js

@@ -52,13 +52,14 @@ export const makeEnvironmentCaptor = (aGlobal, dropNames = false) => {
    *
    * @param {string} optionName
    * @param {string} defaultSetting
-   * @param {string[]} [optOtherNames]
+   * @param {string[]} [optOtherValues]
+   * If provided, the option value must be included or match `defaultSetting`.
    * @returns {string}
    */
   const getEnvironmentOption = (
     optionName,
     defaultSetting,
-    optOtherNames = undefined,
+    optOtherValues = undefined,
   ) => {
     typeof optionName === 'string' ||
       Fail`Environment option name ${q(optionName)} must be a string.`;
@@ -88,12 +89,12 @@ export const makeEnvironmentCaptor = (aGlobal, dropNames = false) => {
         setting = optionValue;
       }
     }
-    optOtherNames === undefined ||
+    optOtherValues === undefined ||
       setting === defaultSetting ||
-      arrayIncludes(optOtherNames, setting) ||
+      arrayIncludes(optOtherValues, setting) ||
       Fail`Unrecognized ${q(optionName)} value ${q(
         setting,
-      )}. Expected one of ${q([defaultSetting, ...optOtherNames])}`;
+      )}. Expected one of ${q([defaultSetting, ...optOtherValues])}`;
     return setting;
   };
   freeze(getEnvironmentOption);
@@ -104,7 +105,7 @@ export const makeEnvironmentCaptor = (aGlobal, dropNames = false) => {
    */
   const getEnvironmentOptionsList = optionName => {
     const option = getEnvironmentOption(optionName, '');
-    return option === '' ? [] : stringSplit(option, ',');
+    return freeze(option === '' ? [] : stringSplit(option, ','));
   };
   freeze(getEnvironmentOptionsList);