feat(parser): rename identifier to defineIdentifier and add IfMissingDefineIdentifier

feat(parser): rename identifier to defineIdentifier and add IfMissing…

Author: RomainLanz

src/env.ts

@@ -58,9 +58,34 @@ export class Env<EnvValues extends Record<string, any>> {
   /**
    * Define an identifier for any environment value. The callback is invoked
    * when the value match the identifier to modify its interpolation.
+   *
+   * @deprecated use `Env.defineIdentifier` instead
    */
   static identifier(name: string, callback: (value: string) => Promise<string> | string): void {
-    EnvParser.identifier(name, callback)
+    return EnvParser.defineIdentifier(name, callback)
+  }
+
+  /**
+   * Define an identifier for any environment value. The callback is invoked
+   * when the value match the identifier to modify its interpolation.
+   */
+  static defineIdentifier(
+    name: string,
+    callback: (value: string) => Promise<string> | string
+  ): void {
+    EnvParser.defineIdentifier(name, callback)
+  }
+
+  /**
+   * Define an identifier for any environment value, if it's not already defined.
+   * The callback is invoked when the value match the identifier to modify its
+   * interpolation.
+   */
+  static defineIdentifierIfMissing(
+    name: string,
+    callback: (value: string) => Promise<string> | string
+  ): void {
+    EnvParser.defineIdentifierIfMissing(name, callback)
   }
 
   /**

src/parser.ts

@@ -66,15 +66,42 @@ export class EnvParser {
   /**
    * Define an identifier for any environment value. The callback is invoked
    * when the value match the identifier to modify its interpolation.
+   *
+   * @deprecated use `EnvParser.defineIdentifier` instead
    */
   static identifier(name: string, callback: (value: string) => Promise<string> | string): void {
+    EnvParser.defineIdentifier(name, callback)
+  }
+
+  /**
+   * Define an identifier for any environment value. The callback is invoked
+   * when the value match the identifier to modify its interpolation.
+   */
+  static defineIdentifier(
+    name: string,
+    callback: (value: string) => Promise<string> | string
+  ): void {
     if (this.#identifiers[name]) {
       throw new E_IDENTIFIER_ALREADY_DEFINED([name])
     }
 
     this.#identifiers[name] = callback
   }
 
+  /**
+   * Define an identifier for any environment value, if it's not already defined.
+   * The callback is invoked when the value match the identifier to modify its
+   * interpolation.
+   */
+  static defineIdentifierIfMissing(
+    name: string,
+    callback: (value: string) => Promise<string> | string
+  ): void {
+    if (typeof this.#identifiers[name] === 'undefined') {
+      this.#identifiers[name] = callback
+    }
+  }
+
   /**
    * Remove an identifier
    */

tests/env.spec.ts

@@ -21,14 +21,64 @@ test.group('Env', (group) => {
 
     cleanup(() => {
       Env.removeIdentifier('file')
+      delete process.env.PORT
+    })
+
+    Env.defineIdentifier('file', (_value: string) => {
+      assert.isTrue(true)
+
+      return '3000'
+    })
+
+    await fs.create('.env', 'PORT=file:romain')
+    await Env.create(fs.baseUrl, {
+      PORT: Env.schema.number(),
+    })
+  })
+
+  test('throw exception when identifier is already defined', async ({ assert, cleanup }) => {
+    assert.plan(1)
+
+    cleanup(() => {
+      Env.removeIdentifier('file')
+      delete process.env.PORT
     })
 
-    Env.identifier('file', (_value: string) => {
+    Env.defineIdentifier('file', (_value: string) => {
+      return '3000'
+    })
+
+    assert.throws(
+      () =>
+        Env.defineIdentifier('file', (_value: string) => {
+          return '3000'
+        }),
+      'The identifier "file" is already defined'
+    )
+  })
+
+  test('silently ignore when adding the same identifier with IfMissing variant', async ({
+    assert,
+    cleanup,
+    fs,
+  }) => {
+    assert.plan(1)
+
+    cleanup(() => {
+      Env.removeIdentifier('file')
+      delete process.env.PORT
+    })
+
+    Env.defineIdentifier('file', (_value: string) => {
       assert.isTrue(true)
 
       return '3000'
     })
 
+    Env.defineIdentifierIfMissing('file', (_value: string) => {
+      return '3000'
+    })
+
     await fs.create('.env', 'PORT=file:romain')
     await Env.create(fs.baseUrl, {
       PORT: Env.schema.number(),

tests/parser.spec.ts

@@ -58,7 +58,57 @@ test.group('Env Parser', () => {
       EnvParser.removeIdentifier('file')
     })
 
-    EnvParser.identifier('file', (_value: string) => {
+    EnvParser.defineIdentifier('file', (_value: string) => {
+      return '3000'
+    })
+
+    const envString = ['ENV_USER=file:romain'].join('\n')
+    const parser = new EnvParser(envString)
+    const parsed = await parser.parse()
+
+    expectTypeOf(parsed).toEqualTypeOf<DotenvParseOutput>()
+    assert.deepEqual(parsed, {
+      ENV_USER: '3000',
+    })
+  })
+
+  test('throw exception when identifier is already defined', async ({ assert, cleanup }) => {
+    cleanup(() => {
+      EnvParser.removeIdentifier('file')
+    })
+
+    EnvParser.defineIdentifier('file', (_value: string) => {
+      return '3000'
+    })
+
+    assert.throws(
+      () =>
+        EnvParser.defineIdentifier('file', (_value: string) => {
+          return '3000'
+        }),
+      'The identifier "file" is already defined'
+    )
+  })
+
+  test('silently ignore when adding the same identifier with IfMissing variant', async ({
+    assert,
+    cleanup,
+    expectTypeOf,
+  }) => {
+    assert.plan(2)
+
+    cleanup(() => {
+      EnvParser.removeIdentifier('file')
+    })
+
+    EnvParser.defineIdentifier('file', (_value: string) => {
+      console.log('Never called')
+      assert.isTrue(true)
+
+      return '3000'
+    })
+
+    EnvParser.defineIdentifierIfMissing('file', (_value: string) => {
       return '3000'
     })