feat: envReplaceLossy

Author: zkochan

config/env-replace/env-replace.docs.mdx

@@ -1,18 +1,58 @@
 ---
 labels: ['configuration']
-description: 'A function for repacing env variables in configuration settings'
+description: 'Functions for replacing env variables in configuration settings'
 ---
 
-API:
+## `envReplace`
+
+Strict mode — throws when a `${VAR}` placeholder has no value and no default.
 
 ```ts
 function envReplace(settingValue: string, env: NodeJS.ProcessEnv): string;
 ```
 
-Usage:
-
 ```ts
 import { envReplace } from '@pnpm/config.env-replace'
 
 envReplace('${foo}', process.env)
 ```
+
+## `envReplaceLossy`
+
+Lossy mode — replaces unresolved `${VAR}` placeholders with `''` and reports
+them in `unresolved` instead of throwing. Resolvable placeholders and
+`${VAR-default}` / `${VAR:-default}` fallbacks elsewhere in the same string
+still expand normally; only the genuinely unresolved bare ones are dropped.
+
+Use this when leaving the literal `${VAR}` in the substituted value would be
+worse than dropping it (e.g. auth tokens in `.npmrc` under OIDC trusted
+publishing).
+
+```ts
+function envReplaceLossy(
+  settingValue: string,
+  env: NodeJS.ProcessEnv
+): { value: string; unresolved: string[] };
+```
+
+```ts
+import { envReplaceLossy } from '@pnpm/config.env-replace'
+
+const { value, unresolved } = envReplaceLossy('${foo}-${missing}', process.env)
+// value:      'foo_value-'
+// unresolved: ['${missing}']
+```
+
+## Placeholder syntax
+
+- `${NAME}` — strict; the env var must be set (otherwise `envReplace` throws,
+  or `envReplaceLossy` substitutes `''` and records the placeholder).
+- `${NAME-fallback}` — `fallback` if `NAME` is unset.
+- `${NAME:-fallback}` — `fallback` if `NAME` is unset **or** an empty string.
+- A leading `\` escapes the placeholder (`\${NAME}` stays literal).
+
+`{ NAME: undefined }` in `env` is treated as **unset** for both functions —
+the same as the key being absent. This matches the
+`Record<string, string | undefined>` shape of `NodeJS.ProcessEnv`, where
+callers (notably tests) routinely model an unset variable as a
+present-but-undefined property.

config/env-replace/env-replace.spec.ts

@@ -1,4 +1,4 @@
-import { envReplace } from './env-replace';
+import { envReplace, envReplaceLossy } from './env-replace';
 
 const ENV = {
   foo: 'foo_value',
@@ -25,3 +25,51 @@ test('fail when the env variable is not found', () => {
   expect(() => envReplace('${foo:-}', ENV)).toThrow(`Failed to replace env in config: \${foo:-}`);
 })
 
+test('treat present-but-undefined env value as unset for fallbacks', () => {
+  // `NodeJS.ProcessEnv` is `Record<string, string | undefined>`. Callers that
+  // construct the env object directly may represent an unset variable as
+  // `{ KEY: undefined }`. `${KEY-default}` must use the fallback in that case.
+  const ENV_WITH_UNDEFINED = { ...ENV, qux: undefined };
+  expect(envReplace('${qux-fallback}', ENV_WITH_UNDEFINED)).toBe('fallback');
+  expect(envReplace('${qux:-fallback}', ENV_WITH_UNDEFINED)).toBe('fallback');
+  expect(() => envReplace('${qux}', ENV_WITH_UNDEFINED))
+    .toThrow(`Failed to replace env in config: \${qux}`);
+})
+
+describe('envReplaceLossy', () => {
+  test('substitutes unresolved placeholders with empty string and records them', () => {
+    const { value, unresolved } = envReplaceLossy('${baz}', ENV);
+    expect(value).toBe('');
+    expect(unresolved).toEqual(['${baz}']);
+  });
+
+  test('preserves resolvable placeholders and default fallbacks alongside unresolved ones', () => {
+    // Mixed value: one resolvable, one unresolved bare, one with a `-default` fallback.
+    // Only the bare unresolved one becomes ''; the others still expand normally.
+    const { value, unresolved } = envReplaceLossy(
+      '${foo}-${baz}-${qux-fallback}',
+      ENV,
+    );
+    expect(value).toBe('foo_value--fallback');
+    expect(unresolved).toEqual(['${baz}']);
+  });
+
+  test('records every unresolved placeholder occurrence in source order', () => {
+    const { value, unresolved } = envReplaceLossy('${a}-${b}-${a}', {});
+    expect(value).toBe('--');
+    expect(unresolved).toEqual(['${a}', '${b}', '${a}']);
+  });
+
+  test('returns the value unchanged and empty unresolved when nothing fails', () => {
+    const { value, unresolved } = envReplaceLossy('-${foo}-${bar}-', ENV);
+    expect(value).toBe('-foo_value-bar_value-');
+    expect(unresolved).toEqual([]);
+  });
+
+  test('respects backslash escapes the same way envReplace does', () => {
+    // Odd backslash count escapes the placeholder; lookup never runs.
+    expect(envReplaceLossy('\\${baz}', ENV)).toEqual({ value: '${baz}', unresolved: [] });
+    // Even count: half collapses to a literal `\`, the placeholder expands.
+    expect(envReplaceLossy('\\\\${foo}', ENV)).toEqual({ value: '\\foo_value', unresolved: [] });
+  });
+});

config/env-replace/env-replace.ts

@@ -1,28 +1,75 @@
 const ENV_EXPR = /(?<!\\)(\\*)\$\{([^${}]+)\}/g
+const ENV_VALUE = /([^:-]+)(:?)-(.+)/
 
-export function envReplace(settingValue: string, env: NodeJS.ProcessEnv): string {
-  return settingValue.replace(ENV_EXPR, replaceEnvMatch.bind(null, env))
+/**
+ * Replace every `${VAR}` (or `${VAR-default}` / `${VAR:-default}`) placeholder
+ * in `settingValue` with the env value resolved from `env`. Throws on the first
+ * placeholder that has no value and no default.
+ */
+export function envReplace (settingValue: string, env: NodeJS.ProcessEnv): string {
+  return replaceWith(settingValue, env, (orig) => {
+    throw new Error(`Failed to replace env in config: ${orig}`)
+  })
 }
 
-function replaceEnvMatch (env: NodeJS.ProcessEnv, orig: string, escape: string, name: string): string {
-  if (escape.length % 2) {
-    return orig.slice((escape.length + 1) / 2)
-  }
-  const envValue = getEnvValue(env, name)
-  if (envValue === undefined) {
-    throw new Error(`Failed to replace env in config: ${orig}`)
-  }
-  return `${(escape.slice(escape.length / 2))}${envValue}`
+export interface EnvReplaceLossyResult {
+  /** The substituted text. Unresolved placeholders are replaced with `''`. */
+  value: string
+  /**
+   * The list of unresolved placeholders (each including its surrounding `${...}`,
+   * in source order). One entry per occurrence — duplicates appear multiple times.
+   * Callers typically surface each as a warning.
+   */
+  unresolved: string[]
 }
 
-const ENV_VALUE = /([^:-]+)(:?)-(.+)/
+/**
+ * Like {@link envReplace}, but replaces unresolved `${VAR}` placeholders with
+ * `''` and reports them in {@link EnvReplaceLossyResult.unresolved} instead of
+ * throwing. Resolvable placeholders and `${VAR-default}` / `${VAR:-default}`
+ * fallbacks still expand normally — only the genuinely unresolved bare ones are
+ * dropped.
+ *
+ * Use this when leaving the literal `${VAR}` in the substituted value would be
+ * worse than dropping it (e.g. auth tokens in `.npmrc` under OIDC trusted
+ * publishing — see https://github.com/pnpm/pnpm/issues/11513).
+ */
+export function envReplaceLossy (settingValue: string, env: NodeJS.ProcessEnv): EnvReplaceLossyResult {
+  const unresolved: string[] = []
+  const value = replaceWith(settingValue, env, (orig) => {
+    unresolved.push(orig)
+    return ''
+  })
+  return { value, unresolved }
+}
+
+// Shared substitution loop. `onUnresolved` decides what to splice in (and may
+// throw) when a placeholder has no value and no default.
+function replaceWith (
+  settingValue: string,
+  env: NodeJS.ProcessEnv,
+  onUnresolved: (orig: string) => string
+): string {
+  return settingValue.replace(ENV_EXPR, (orig: string, escape: string, name: string) => {
+    if (escape.length % 2) return orig.slice((escape.length + 1) / 2)
+    const halfEscape = escape.slice(escape.length / 2)
+    const envValue = getEnvValue(env, name)
+    if (envValue === undefined) return `${halfEscape}${onUnresolved(orig)}`
+    return `${halfEscape}${envValue}`
+  })
+}
 
 function getEnvValue (env: NodeJS.ProcessEnv, name: string): string | undefined {
   const matched = name.match(ENV_VALUE)
   if (!matched) return env[name]
   const [, variableName, colon, fallback] = matched
-  if (Object.prototype.hasOwnProperty.call(env, variableName)) {
-    return !env[variableName] && colon ? fallback : env[variableName]
-  }
-  return fallback
+  // Treat `{ KEY: undefined }` as unset rather than "explicitly empty": the
+  // `NodeJS.ProcessEnv` (= `Record<string, string | undefined>`) signature lets
+  // callers represent an unset variable as a present-but-undefined property,
+  // and `${KEY-default}` must reach the fallback in that case. Using
+  // `hasOwnProperty` would treat the property as set and return `undefined`
+  // instead of `fallback`.
+  const v = env[variableName]
+  if (v === undefined) return fallback
+  return !v && colon ? fallback : v
 }

config/env-replace/index.ts

@@ -1 +1 @@
-export { envReplace } from './env-replace';
+export { envReplace, envReplaceLossy, type EnvReplaceLossyResult } from './env-replace';