alchemy-run · sam-goodwin · Jun 10, 2026
diff --git a/packages/aws/README.md b/packages/aws/README.md
@@ -16,7 +16,7 @@ import * as Stream from "effect/Stream";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import * as Lambda from "@distilled.cloud/aws/lambda";
 import * as S3 from "@distilled.cloud/aws/s3";
-import { Credentials, Region } from "@distilled.cloud/aws";
+import { Config, Credentials } from "@distilled.cloud/aws";
 
 const program = Effect.gen(function* () {
   yield* S3.putObject({
@@ -39,7 +39,7 @@ const program = Effect.gen(function* () {
 
 const AwsLive = Layer.mergeAll(
   FetchHttpClient.layer,
-  Region.fromEnv(),
+  Config.fromEnv(),
   Credentials.fromChain(),
 );
 
@@ -48,14 +48,31 @@ program.pipe(Effect.provide(AwsLive), Effect.runPromise);
 
 ## Configuration
 
-### Region
+### AWSConfig
 
-`Region.fromEnv()` reads from the `AWS_REGION` environment variable (falls back to `AWS_DEFAULT_REGION`):
+The `AWSConfig` service provides the region and an optional custom endpoint. `Config.fromEnv()` reads the region from the `AWS_REGION` environment variable (falls back to `AWS_DEFAULT_REGION`):
 
 ```bash
 AWS_REGION=us-east-1
 ```
 
+You can also provide it directly — useful for custom endpoints like LocalStack:
+
+```typescript
+import { Effect } from "effect";
+import { AWSConfig } from "@distilled.cloud/aws";
+
+program.pipe(
+  Effect.provideService(
+    AWSConfig,
+    Effect.succeed({
+      region: "us-east-1",
+      endpoint: "http://localhost:4566",
+    }),
+  ),
+);
+```
+
 ### Credentials
 
 `Credentials.fromChain()` uses the standard AWS credential provider chain, which tries each source in order until one succeeds:

diff --git a/packages/aws/scripts/generate.ts b/packages/aws/scripts/generate.ts
@@ -55,7 +55,7 @@ class SdkFile extends Context.Service<
     allSchemaNames: Set<string>;
     // Import reference names (resolved based on conflicts)
     credsRef: string;
-    rgnRef: string;
+    cfgRef: string;
     commonErrorsRef: string;
     streamRef: string;
     // Map of newtype names to their underlying TypeScript type (e.g., PhoneNumber -> string)
@@ -2786,7 +2786,7 @@ const generateClient = Effect.fn(function* (
         const apiFn = paginatedTrait ? "API.makePaginated" : "API.make";
 
         // Dependencies type for operations
-        const depsType = `${sdkFile.credsRef} | ${sdkFile.rgnRef} | HttpClient.HttpClient`;
+        const depsType = `${sdkFile.credsRef} | ${sdkFile.cfgRef} | HttpClient.HttpClient`;
 
         // Map Smithy primitives to TypeScript types
         const smithyPrimitiveToTs: Record<string, string> = {
@@ -2966,10 +2966,10 @@ const generateClient = Effect.fn(function* (
       sdkFile.credsRef === "Creds"
         ? 'import type { Credentials as Creds } from "../credentials.ts";'
         : 'import type { Credentials } from "../credentials.ts";';
-    const regionImport =
-      sdkFile.rgnRef === "Rgn"
-        ? 'import type { Region as Rgn } from "../region.ts";'
-        : 'import type { Region } from "../region.ts";';
+    const configImport =
+      sdkFile.cfgRef === "Cfg"
+        ? 'import type { AWSConfig as Cfg } from "../config.ts";'
+        : 'import type { AWSConfig } from "../config.ts";';
     const commonErrorsImport =
       sdkFile.commonErrorsRef === "CommonErr"
         ? 'import type { CommonErrors as CommonErr } from "../errors.ts";'
@@ -2988,7 +2988,7 @@ const generateClient = Effect.fn(function* (
       __CATEGORY_IMPORT__
       ${credentialsImport}
       ${commonErrorsImport}
-      ${regionImport}
+      ${configImport}
       __SENSITIVE_IMPORT__`;
 
     // Define service-level constants
@@ -3135,11 +3135,11 @@ const generateClient = Effect.fn(function* (
 
   // Pre-compute conflict resolution for imports
   const hasCredentialsConflict = allSchemaNames.has("Credentials");
-  const hasRegionConflict = allSchemaNames.has("Region");
+  const hasConfigConflict = allSchemaNames.has("AWSConfig");
   const hasCommonErrorsConflict = allSchemaNames.has("CommonErrors");
 
   const credsRef = hasCredentialsConflict ? "Creds" : "Credentials";
-  const rgnRef = hasRegionConflict ? "Rgn" : "Region";
+  const cfgRef = hasConfigConflict ? "Cfg" : "AWSConfig";
   const commonErrorsRef = hasCommonErrorsConflict
     ? "CommonErr"
     : "CommonErrors";
@@ -3214,7 +3214,7 @@ const generateClient = Effect.fn(function* (
       allUnionNames,
       allSchemaNames,
       credsRef,
-      rgnRef,
+      cfgRef,
       commonErrorsRef,
       streamRef,
       newtypes: yield* Ref.make<Map<string, string>>(new Map()),

diff --git a/packages/aws/src/client/api.ts b/packages/aws/src/client/api.ts
@@ -22,9 +22,8 @@ import {
   type ResponseParserOptions,
 } from "./response-parser.ts";
 
+import { AWSConfig } from "../config.ts";
 import * as Credentials from "../credentials.browser.ts";
-import * as Endpoint from "../endpoint.ts";
-import * as Region from "../region.ts";
 
 export interface MakeOptions extends ResponseParserOptions {}
 
@@ -99,19 +98,20 @@ export const make = <Op extends Operation<any, any, any>>(
 
     // Sign the request
     const credentials = yield* yield* Credentials.Credentials;
-    const region = yield* yield* Region.Region;
+    const config = yield* yield* AWSConfig;
+    const region = config.region;
     const serviceName = sigv4?.name ?? "s3";
 
     // Resolve endpoint and adjust request path if needed
     let endpoint: string;
     let resolvedRequest = request;
     let signingRegion = region; // Default to context region
     let signingServiceName = serviceName; // Default to service name from sigv4 trait
-    const customEndpoint = yield* Effect.serviceOption(Endpoint.Endpoint);
+    const customEndpoint = Option.fromUndefinedOr(config.endpoint);
 
     if (Option.isSome(customEndpoint)) {
       // User provided a custom endpoint - use it directly
-      endpoint = yield* customEndpoint.value;
+      endpoint = customEndpoint.value;
     } else if (rulesResolver) {
       // Use the rules resolver - it handles endpoint resolution AND path adjustment
       const resolved = yield* rulesResolver({

diff --git a/packages/aws/src/region.ts → packages/aws/src/config.ts b/packages/aws/src/region.ts → packages/aws/src/config.ts
@@ -3,17 +3,23 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 
-export class Region extends Context.Service<
-  Region,
-  Effect.Effect<RegionName>
->()("AWS::Region") {}
+export class AWSConfig extends Context.Service<
+  AWSConfig,
+  Effect.Effect<{
+    readonly region: RegionName;
+    readonly endpoint?: string | undefined;
+  }>
+>()("AWS::Config") {}
 
 export const fromEnv = () =>
   Layer.succeed(
-    Region,
-    Config.string("AWS_REGION")
-      .pipe(Config.orElse(() => Config.string("AWS_DEFAULT_REGION")))
-      .pipe(Effect.orDie),
+    AWSConfig,
+    Effect.map(
+      Config.string("AWS_REGION")
+        .pipe(Config.orElse(() => Config.string("AWS_DEFAULT_REGION")))
+        .pipe(Effect.orDie),
+      (region) => ({ region }),
+    ),
   );
 
 export type RegionName =

diff --git a/packages/aws/src/endpoint.ts b/packages/aws/src/endpoint.ts
diff --git a/packages/aws/src/index.browser.ts b/packages/aws/src/index.browser.ts
@@ -13,11 +13,12 @@ export * as Auth from "./auth.browser.ts";
 export * as Credentials from "./credentials.browser.ts";
 
 /**
- * AWS Endpoint configuration for custom or local endpoints.
+ * AWS configuration service (region and optional custom endpoint).
  *
  * @since 0.0.0
  */
-export * as Endpoint from "./endpoint.ts";
+export * as Config from "./config.ts";
+export { AWSConfig } from "./config.ts";
 
 /**
  * Common AWS error types shared across all services.
@@ -26,13 +27,6 @@ export * as Endpoint from "./endpoint.ts";
  */
 export * as Errors from "./errors.ts";
 
-/**
- * AWS Region configuration.
- *
- * @since 0.0.0
- */
-export * as Region from "./region.ts";
-
 /**
  * Retry policy configuration for AWS API calls.
  *

diff --git a/packages/aws/src/index.ts b/packages/aws/src/index.ts
@@ -13,11 +13,12 @@ export * as Auth from "./auth.ts";
 export * as Credentials from "./credentials.ts";
 
 /**
- * AWS Endpoint configuration for custom or local endpoints.
+ * AWS configuration service (region and optional custom endpoint).
  *
  * @since 0.0.0
  */
-export * as Endpoint from "./endpoint.ts";
+export * as Config from "./config.ts";
+export { AWSConfig } from "./config.ts";
 
 /**
  * Common AWS error types shared across all services.
@@ -26,13 +27,6 @@ export * as Endpoint from "./endpoint.ts";
  */
 export * as Errors from "./errors.ts";
 
-/**
- * AWS Region configuration.
- *
- * @since 0.0.0
- */
-export * as Region from "./region.ts";
-
 /**
  * Retry policy configuration for AWS API calls.
  *