Better DX for nested configs

[kibertoad]

Changes

Summary

• Add optional { path } parameter to getEnvaseAwsConfig() that generates computed resolvers scoped to the
  specified config key (e.g., fullParsedConfig.aws)
• Remove the need for consumers to manually wrap computed resolvers when nesting AWS config under a key
• Update README with separate sections for nested and flat config usage

Problem

When consumers nest AWS config under a key like aws, envase passes the full parsed config to computed resolvers.
Since the credentials resolver expects { accessKeyId, secretAccessKey } at the root, consumers had to write a
manual wrapper:

computed: {
  aws: {
    credentials: (raw) => awsConfig.computed.credentials(raw.aws),
  },
}

Solution

getEnvaseAwsConfig({ path: 'aws' }) generates resolvers that read from fullParsedConfig.aws automatically:

  const awsConfig = getEnvaseAwsConfig({ path: 'aws' })

  createConfig(process.env, {
    schema: { aws: awsConfig.schema },
    computed: { aws: awsConfig.computed },  // just works
  })

Omitting path preserves the existing flat spread behavior.

Checklist

• Apply one of following labels; major, minor, patch or skip-release
• I've updated the documentation, or no changes were necessary
• I've updated the tests, or no changes were necessary

AI Assistance Tracking

We're running a metric to understand where AI assists our engineering work. Please select exactly one of the options below:

Mark "Yes" if AI helped in any part of this work, for example: generating code, refactoring, debugging support,
explaining something, reviewing an idea, or suggesting an approach.

• Yes, AI assisted with this PR
• No, AI did not assist with this PR

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated AWS config integration guidance with detailed examples for implementing both nested and flat configuration patterns, clarifying usage scenarios for each approach.

• New Features

  • Enhanced getEnvaseAwsConfig() with optional path configuration to control how AWS credentials are resolved from different configuration layouts, enabling flexible integration patterns for both nested namespace and root-level structures.

Walkthrough

This change enhances AWS configuration flexibility for envase integration by converting getEnvaseAwsConfig from a static constant to a generic function. It introduces EnvaseAwsConfigOptions with an optional path parameter that enables users to specify whether AWS fields should be nested under a particular key (e.g., aws) or spread at the root level. The implementation uses generics and conditional type logic to maintain type safety for both nesting strategies. Supporting types like EnvaseAwsConfigComputedType and EnvaseAwsConfigFragments are made generic to accommodate different raw configuration shapes. Documentation and tests are updated to demonstrate both usage patterns.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Better DX for nested configs' accurately summarizes the main change: improving developer experience by adding support for nested config paths.
Description check	✅ Passed	The description covers the problem, solution, and updates; all checklist items are marked complete. Documentation (README) and tests were updated as required.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/improve-envase-support

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/app/aws-config/src/envaseAwsConfig.ts (1)

110-133: Consider guarding against empty string path.

The implementation correctly handles the path option, but an empty string "" is truthy in the conditional check on line 123, yet accessing raw[""] would be semantically incorrect usage. Consider adding validation or documenting this edge case.

🛡️ Optional: Add guard for empty string path

 function createAwsComputed<TPath extends string | undefined>(
   path?: TPath,
 ): EnvaseAwsConfigFragments<TPath>['computed'] {
   const resolveCredentials = (awsRaw: {
     accessKeyId?: string
     secretAccessKey?: string
   }): AwsCredentialIdentity | Provider<AwsCredentialIdentity> => {
     if (awsRaw.accessKeyId && awsRaw.secretAccessKey) {
       return { accessKeyId: awsRaw.accessKeyId, secretAccessKey: awsRaw.secretAccessKey }
     }
     return createCredentialChain(fromTokenFile(), fromInstanceMetadata(), fromEnv(), fromIni())
   }

-  if (path) {
+  if (path && path.length > 0) {
     return {
       // biome-ignore lint/suspicious/noExplicitAny: raw config shape depends on consumer's schema
       credentials: (raw: any) => resolveCredentials(raw[path]),
     } as EnvaseAwsConfigFragments<TPath>['computed']
   }

   return {
     credentials: resolveCredentials,
   } as EnvaseAwsConfigFragments<TPath>['computed']
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/app/aws-config/src/envaseAwsConfig.ts` around lines 110 - 133, The
createAwsComputed function currently treats any truthy path (including empty
string) as a valid key and calls credentials: (raw: any) =>
resolveCredentials(raw[path]); add a guard to detect and reject empty-string
paths: validate the path parameter (e.g., if (path === '' || path == null) treat
it as no-path) before the conditional that returns the object with credentials:
(raw: any) => resolveCredentials(raw[path]); and update the branch that returns
credentials: resolveCredentials accordingly so resolveCredentials is never
called with raw[''] — either throw a clear error for empty string paths or fall
back to the no-path behavior; reference createAwsComputed, path,
resolveCredentials, and the credentials property to locate the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/app/aws-config/src/envaseAwsConfig.ts`:
- Around line 110-133: The createAwsComputed function currently treats any
truthy path (including empty string) as a valid key and calls credentials: (raw:
any) => resolveCredentials(raw[path]); add a guard to detect and reject
empty-string paths: validate the path parameter (e.g., if (path === '' || path
== null) treat it as no-path) before the conditional that returns the object
with credentials: (raw: any) => resolveCredentials(raw[path]); and update the
branch that returns credentials: resolveCredentials accordingly so
resolveCredentials is never called with raw[''] — either throw a clear error for
empty string paths or fall back to the no-path behavior; reference
createAwsComputed, path, resolveCredentials, and the credentials property to
locate the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: lokalise/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 640e400b-abbb-4f9c-baa7-2199fecfa6f4

📥 Commits

Reviewing files that changed from the base of the PR and between 8d40918 and b7d8340.

📒 Files selected for processing (4)

• packages/app/aws-config/README.md
• packages/app/aws-config/src/envaseAwsConfig.spec.ts
• packages/app/aws-config/src/envaseAwsConfig.ts
• packages/app/aws-config/src/index.ts