@dyanet/nextjs-config-aws 1.0.0-beta.1 → 1.0.0

package/dist/cjs/server/get-config.js

@@ -2,6 +2,31 @@
 /**
  * Server-side configuration loading for Next.js applications.
  * Provides a cached getConfig() function that uses ConfigManager from @dyanet/config-aws.
+ *
+ * This module provides a simplified, opinionated API that hides loader complexity.
+ * For advanced usage such as custom loaders, direct AWS SDK integration, or
+ * fine-grained control over configuration loading, import from `@dyanet/config-aws` directly:
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with custom loaders
+ * import {
+ *   ConfigManager,
+ *   EnvironmentLoader,
+ *   SecretsManagerLoader,
+ *   SSMParameterStoreLoader,
+ * } from '@dyanet/config-aws';
+ *
+ * const manager = new ConfigManager({
+ *   loaders: [
+ *     new EnvironmentLoader({ prefix: 'APP_' }),
+ *     new SecretsManagerLoader({ secretName: '/my-app/config' }),
+ *   ],
+ *   schema: mySchema,
+ * });
+ * await manager.load();
+ * const config = manager.getAll();
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getConfig = getConfig;
@@ -11,6 +36,8 @@ exports.getAwsApiCallCount = getAwsApiCallCount;
 exports.resetAwsApiCallCount = resetAwsApiCallCount;
 exports.invalidateConfig = invalidateConfig;
 const config_aws_1 = require("@dyanet/config-aws");
+const environment_1 = require("./internal/environment");
+const loader_factory_1 = require("./internal/loader-factory");
 /**
  * Cache storage for configuration
  * Uses a Map to support multiple cache keys (for different option combinations)
@@ -22,15 +49,16 @@ const configCache = new Map();
  */
 let awsApiCallCount = 0;
 /**
- * Generate a cache key from options
+ * Generate a cache key from options.
+ * The cache key is based on aws options, environment, and forceAwsInDev.
  * @internal
  */
-function generateCacheKey(options) {
-    const loaderNames = options.loaders?.map((l) => l.getName()).join(',') ?? '';
-    const precedence = Array.isArray(options.precedence)
-        ? options.precedence.map((p) => `${p.loader}:${p.priority}`).join(',')
-        : options.precedence ?? 'aws-first';
-    return `${loaderNames}|${precedence}`;
+function generateCacheKey(options, resolvedEnvironment) {
+    return JSON.stringify({
+        aws: options.aws,
+        environment: resolvedEnvironment,
+        forceAwsInDev: options.forceAwsInDev ?? false,
+    });
 }
 /**
  * Check if a cache entry is still valid
@@ -44,12 +72,18 @@ function isCacheValid(entry) {
 /**
  * Load configuration for Next.js server-side use.
  *
- * This function provides caching to avoid repeated AWS API calls during request handling.
- * Configuration is cached based on the loader configuration and precedence strategy.
+ * This function provides automatic environment detection and caching to avoid
+ * repeated AWS API calls during request handling. Configuration is cached based
+ * on the AWS options, environment, and forceAwsInDev setting.
+ *
+ * Environment Behavior:
+ * - development: env vars + .env.local/.env files, AWS only if forceAwsInDev
+ * - production: env vars + .env file + AWS sources (if configured)
+ * - test: env vars only (no file or AWS access)
  *
  * @example
  * ```typescript
- * import { getConfig, EnvironmentLoader, SecretsManagerLoader } from '@dyanet/nextjs-config-aws';
+ * import { getConfig } from '@dyanet/nextjs-config-aws';
  * import { z } from 'zod';
  *
  * const schema = z.object({
@@ -57,29 +91,34 @@ function isCacheValid(entry) {
  *   API_KEY: z.string(),
  * });
  *
- * // In a Server Component or API route
- * export default async function Page() {
- *   const config = await getConfig({
- *     schema,
- *     loaders: [
- *       new EnvironmentLoader(),
- *       new SecretsManagerLoader({ secretName: '/my-app/config' }),
- *     ],
- *     precedence: 'aws-first',
- *   });
+ * // Minimal usage - auto-detects environment
+ * const config = await getConfig({ schema });
  *
- *   return <div>DB: {config.DATABASE_URL}</div>;
- * }
+ * // With AWS Secrets Manager (loaded in production)
+ * const config = await getConfig({
+ *   schema,
+ *   aws: { secretName: '/my-app/config', region: 'us-east-1' }
+ * });
+ *
+ * // Force AWS in development for testing
+ * const config = await getConfig({
+ *   schema,
+ *   aws: { secretName: '/my-app/config' },
+ *   forceAwsInDev: true
+ * });
  * ```
  *
  * @param options Configuration options
  * @returns Promise resolving to the validated configuration object
+ * @throws {ValidationError} When schema validation fails (includes invalid key names)
  */
 async function getConfig(options = {}) {
-    const { schema, loaders = [], precedence = 'aws-first', cache = true, cacheTTL = 60000, // 1 minute default
+    const { schema, aws, environment: explicitEnvironment, forceAwsInDev = false, cache = true, cacheTTL = 60000, // 1 minute default
     enableLogging = false, } = options;
-    // Generate cache key
-    const cacheKey = generateCacheKey(options);
+    // Determine environment: explicit option takes precedence over auto-detection
+    const resolvedEnvironment = explicitEnvironment ?? (0, environment_1.detectEnvironment)();
+    // Generate cache key based on aws options, environment, and forceAwsInDev
+    const cacheKey = generateCacheKey(options, resolvedEnvironment);
     // Check cache if enabled
     if (cache) {
         const cached = configCache.get(cacheKey);
@@ -89,11 +128,17 @@ async function getConfig(options = {}) {
     }
     // Increment API call counter (for testing)
     awsApiCallCount++;
-    // Create ConfigManager with provided options
+    // Create loaders using the internal factory
+    const loaders = (0, loader_factory_1.createLoaders)({
+        environment: resolvedEnvironment,
+        aws,
+        forceAwsInDev,
+    });
+    // Create ConfigManager with generated loaders
     const managerOptions = {
         loaders,
         schema,
-        precedence,
+        precedence: 'aws-first',
         validateOnLoad: true,
         enableLogging,
     };
@@ -147,7 +192,8 @@ function resetAwsApiCallCount() {
  * @param options The options used to create the cache entry
  */
 function invalidateConfig(options) {
-    const cacheKey = generateCacheKey(options);
+    const resolvedEnvironment = options.environment ?? (0, environment_1.detectEnvironment)();
+    const cacheKey = generateCacheKey(options, resolvedEnvironment);
     configCache.delete(cacheKey);
 }
 //# sourceMappingURL=get-config.js.map

package/dist/cjs/server/get-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-config.js","sourceRoot":"","sources":["../../../src/server/get-config.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAyGH,8BAoDC;AAMD,4CAEC;AAMD,gDAEC;AAOD,gDAEC;AAOD,oDAEC;AAMD,4CAGC;AArMD,mDAM4B;AA6B5B;;;GAGG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAA+B,CAAC;AAE3D;;;GAGG;AACH,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB;;;GAGG;AACH,SAAS,gBAAgB,CAAI,OAA6B;IACxD,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC7E,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;QAClD,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QACtE,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,WAAW,CAAC;IACtC,OAAO,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAI,KAAgC;IACvD,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACI,KAAK,UAAU,SAAS,CAC7B,UAAgC,EAAE;IAElC,MAAM,EACJ,MAAM,EACN,OAAO,GAAG,EAAE,EACZ,UAAU,GAAG,WAAW,EACxB,KAAK,GAAG,IAAI,EACZ,QAAQ,GAAG,KAAK,EAAE,mBAAmB;IACrC,aAAa,GAAG,KAAK,GACtB,GAAG,OAAO,CAAC;IAEZ,qBAAqB;IACrB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAE3C,yBAAyB;IACzB,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAA8B,CAAC;QACtE,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,eAAe,EAAE,CAAC;IAElB,6CAA6C;IAC7C,MAAM,cAAc,GAA4B;QAC9C,OAAO;QACP,MAAM;QACN,UAAU;QACV,cAAc,EAAE,IAAI;QACpB,aAAa;KACd,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,0BAAa,CAAI,cAAc,CAAC,CAAC;IACrD,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IAErB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAE3C,4BAA4B;IAC5B,IAAI,KAAK,IAAI,UAAU,EAAE,CAAC;QACxB,MAAM,KAAK,GAAkB;YAC3B,MAAM;YACN,UAAU;YACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ;SACjC,CAAC;QACF,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,KAA4B,CAAC,CAAC;IAC1D,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB;IAC9B,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB;IAChC,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,OAAO,eAAe,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB;IAClC,eAAe,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAI,OAA6B;IAC/D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC3C,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"get-config.js","sourceRoot":"","sources":["../../../src/server/get-config.ts"],"names":[],"mappings":"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"}

package/dist/cjs/server/internal/environment.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Environment detection utilities for Next.js configuration.
+ * @internal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectEnvironment = detectEnvironment;
+/**
+ * Detect the current environment mode based on NODE_ENV.
+ *
+ * @returns The detected environment mode:
+ *   - 'production' if NODE_ENV is 'production'
+ *   - 'test' if NODE_ENV is 'test'
+ *   - 'development' for all other cases (including undefined)
+ *
+ * @example
+ * ```typescript
+ * // NODE_ENV=production
+ * detectEnvironment(); // 'production'
+ *
+ * // NODE_ENV=test
+ * detectEnvironment(); // 'test'
+ *
+ * // NODE_ENV=development or undefined
+ * detectEnvironment(); // 'development'
+ * ```
+ */
+function detectEnvironment() {
+    const nodeEnv = process.env['NODE_ENV'];
+    if (nodeEnv === 'production') {
+        return 'production';
+    }
+    if (nodeEnv === 'test') {
+        return 'test';
+    }
+    return 'development';
+}
+//# sourceMappingURL=environment.js.map

package/dist/cjs/server/internal/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../../src/server/internal/environment.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA2BH,8CAYC;AAhCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,iBAAiB;IAC/B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAExC,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;QAC7B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/cjs/server/internal/index.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Internal utilities for Next.js configuration.
+ * These are not exported from the public API.
+ * @internal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLoaders = exports.detectEnvironment = void 0;
+var environment_1 = require("./environment");
+Object.defineProperty(exports, "detectEnvironment", { enumerable: true, get: function () { return environment_1.detectEnvironment; } });
+var loader_factory_1 = require("./loader-factory");
+Object.defineProperty(exports, "createLoaders", { enumerable: true, get: function () { return loader_factory_1.createLoaders; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/server/internal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/server/internal/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,6CAAwE;AAA/D,gHAAA,iBAAiB,OAAA;AAC1B,mDAA4E;AAAnE,+GAAA,aAAa,OAAA"}

package/dist/cjs/server/internal/loader-factory.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Internal loader factory for Next.js configuration.
+ * Creates loaders based on environment and options.
+ * @internal
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLoaders = createLoaders;
+const config_aws_1 = require("@dyanet/config-aws");
+/**
+ * Environment Behavior Matrix:
+ *
+ * | Environment | Env Vars | .env Files           | AWS Sources           |
+ * |-------------|----------|----------------------|-----------------------|
+ * | development | ✓        | .env.local, .env     | Only if forceAwsInDev |
+ * | production  | ✓        | .env                 | ✓ (if configured)     |
+ * | test        | ✓        | ✗                    | ✗                     |
+ */
+/**
+ * Create loaders based on environment and options.
+ *
+ * This factory implements the environment behavior matrix:
+ * - development: env vars + .env.local/.env files, AWS only if forceAwsInDev
+ * - production: env vars + .env file + AWS sources (if configured)
+ * - test: env vars only (no file or AWS access)
+ *
+ * @param options - Factory options including environment and AWS config
+ * @returns Array of ConfigLoader instances
+ */
+function createLoaders(options) {
+    const { environment, aws, forceAwsInDev = false } = options;
+    const loaders = [];
+    // Always include environment variables
+    loaders.push(new config_aws_1.EnvironmentLoader());
+    // Include .env files based on environment
+    if (environment === 'development') {
+        loaders.push(new config_aws_1.EnvFileLoader({ paths: ['.env.local', '.env'] }));
+    }
+    else if (environment === 'production') {
+        loaders.push(new config_aws_1.EnvFileLoader({ paths: ['.env'] }));
+    }
+    // test environment: no file loading
+    // Include AWS loaders in production or when forced in development
+    const shouldLoadAws = environment === 'production' || (environment === 'development' && forceAwsInDev);
+    if (shouldLoadAws && aws) {
+        if (aws.secretName) {
+            loaders.push(new config_aws_1.SecretsManagerLoader({
+                secretName: aws.secretName,
+                region: aws.region,
+            }));
+        }
+        if (aws.ssmPrefix) {
+            loaders.push(new config_aws_1.SSMParameterStoreLoader({
+                parameterPath: aws.ssmPrefix,
+                region: aws.region,
+            }));
+        }
+    }
+    return loaders;
+}
+//# sourceMappingURL=loader-factory.js.map

package/dist/cjs/server/internal/loader-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-factory.js","sourceRoot":"","sources":["../../../../src/server/internal/loader-factory.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAwDH,sCAmCC;AAzFD,mDAM4B;AA2B5B;;;;;;;;GAQG;AAEH;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAAC,OAA6B;IACzD,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,aAAa,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IAC5D,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,uCAAuC;IACvC,OAAO,CAAC,IAAI,CAAC,IAAI,8BAAiB,EAAE,CAAC,CAAC;IAEtC,0CAA0C;IAC1C,IAAI,WAAW,KAAK,aAAa,EAAE,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,IAAI,0BAAa,CAAC,EAAE,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;SAAM,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,IAAI,0BAAa,CAAC,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,oCAAoC;IAEpC,kEAAkE;IAClE,MAAM,aAAa,GAAG,WAAW,KAAK,YAAY,IAAI,CAAC,WAAW,KAAK,aAAa,IAAI,aAAa,CAAC,CAAC;IAEvG,IAAI,aAAa,IAAI,GAAG,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,IAAI,iCAAoB,CAAC;gBACpC,UAAU,EAAE,GAAG,CAAC,UAAU;gBAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC,CAAC;QACN,CAAC;QAED,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAClB,OAAO,CAAC,IAAI,CAAC,IAAI,oCAAuB,CAAC;gBACvC,aAAa,EAAE,GAAG,CAAC,SAAS;gBAC5B,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC,CAAC;QACN,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/esm/client/env.js

@@ -4,11 +4,19 @@
  * This module provides a function to read runtime environment variables
  * that were injected by the PublicEnvScript server component.
  *
+ * @remarks
+ * This is part of the simplified Next.js API. For advanced configuration loading
+ * with custom loaders or direct AWS SDK integration, import from `@dyanet/config-aws` directly:
+ *
+ * ```typescript
+ * import { ConfigManager, EnvironmentLoader } from '@dyanet/config-aws';
+ * ```
+ *
  * @example
  * ```tsx
  * 'use client';
  *
- * import { env } from '@dyanet/nextjs-config-aws/client';
+ * import { env } from '@dyanet/nextjs-config-aws';
  *
  * function MyComponent() {
  *   const apiUrl = env('API_URL');

package/dist/esm/client/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/client/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAYH;;GAEG;AACH,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,SAAS,YAAY,CAAC,eAAuB,qBAAqB;IAChE,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,kDAAkD;QAClD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACpC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,MAAgC,CAAC;IAC1C,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAoCD;;GAEG;AACH,MAAM,UAAU,GAAG,CAAI,GAAW,EAAE,YAAgB;IAClD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AA6BD;;GAEG;AACH,MAAM,UAAU,OAAO,CAAI,YAAoB,EAAE,GAAW,EAAE,YAAgB;IAC5E,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,eAAuB,qBAAqB;IACpE,OAAO,EAAE,GAAG,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,eAAuB,qBAAqB;IAC9E,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,OAAO,GAAG,IAAI,MAAM,CAAC;AACvB,CAAC;AAED,eAAe,GAAG,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/client/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAYH;;GAEG;AACH,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,SAAS,YAAY,CAAC,eAAuB,qBAAqB;IAChE,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,kDAAkD;QAClD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACpC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,MAAgC,CAAC;IAC1C,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAoCD;;GAEG;AACH,MAAM,UAAU,GAAG,CAAI,GAAW,EAAE,YAAgB;IAClD,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AA6BD;;GAEG;AACH,MAAM,UAAU,OAAO,CAAI,YAAoB,EAAE,GAAW,EAAE,YAAgB;IAC5E,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,eAAuB,qBAAqB;IACpE,OAAO,EAAE,GAAG,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,eAAuB,qBAAqB;IAC9E,MAAM,MAAM,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAC1C,OAAO,GAAG,IAAI,MAAM,CAAC;AACvB,CAAC;AAED,eAAe,GAAG,CAAC"}

package/dist/esm/components/public-env-script.js

@@ -5,6 +5,10 @@
  * into the client-side JavaScript context, enabling runtime environment variable access
  * without requiring NEXT_PUBLIC_ prefixes at build time.
  *
+ * @remarks
+ * This is part of the simplified Next.js API. For advanced configuration loading
+ * with custom loaders or direct AWS SDK integration, import from `@dyanet/config-aws` directly.
+ *
  * @example
  * ```tsx
  * // In your root layout.tsx

package/dist/esm/components/public-env-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-env-script.js","sourceRoot":"","sources":["../../../src/components/public-env-script.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAkC/B;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAuC,EACvC,UAAqB,EACrB,YAAqB;IAErB,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,4CAA4C;IAC5C,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,0CAA0C;IAC1C,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,6DAA6D;IAC7D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmC,EACnC,YAAoB;IAEpB,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC/C,OAAO,UAAU,YAAY,IAAI,UAAU,GAAG,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,UAAU,EACV,YAAY,EACZ,YAAY,GAAG,OAAO,EACtB,KAAK,GACgB;IACrB,4DAA4D;IAC5D,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,GAAyC,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;IAE/G,4CAA4C;IAC5C,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8BAA8B;IAC9B,MAAM,aAAa,GAAG,qBAAqB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEvE,qBAAqB;IACrB,MAAM,WAAW,GAAkD;QACjE,uBAAuB,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;KACnD,CAAC;IAEF,2CAA2C;IAC3C,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED,OAAO,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"public-env-script.js","sourceRoot":"","sources":["../../../src/components/public-env-script.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAkC/B;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAuC,EACvC,UAAqB,EACrB,YAAqB;IAErB,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,4CAA4C;IAC5C,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,0CAA0C;IAC1C,IAAI,YAAY,EAAE,CAAC;QACjB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,6DAA6D;IAC7D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmC,EACnC,YAAoB;IAEpB,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC/C,OAAO,UAAU,YAAY,IAAI,UAAU,GAAG,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,UAAU,EACV,YAAY,EACZ,YAAY,GAAG,OAAO,EACtB,KAAK,GACgB;IACrB,4DAA4D;IAC5D,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC,GAAyC,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;IAE/G,4CAA4C;IAC5C,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8BAA8B;IAC9B,MAAM,aAAa,GAAG,qBAAqB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAEvE,qBAAqB;IACrB,MAAM,WAAW,GAAkD;QACjE,uBAAuB,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE;KACnD,CAAC;IAEF,2CAA2C;IAC3C,IAAI,KAAK,EAAE,CAAC;QACV,WAAW,CAAC,KAAK,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED,OAAO,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACpD,CAAC;AAED,eAAe,eAAe,CAAC"}

package/dist/esm/index.js

@@ -2,14 +2,55 @@
  * @dyanet/nextjs-config-aws
  *
  * Next.js adapter for AWS configuration management.
- * Provides server-side configuration loading, React context providers,
- * and runtime environment variable support for Next.js applications.
+ * Provides a simplified, opinionated API for loading configuration
+ * with automatic environment detection and AWS integration.
+ *
+ * @example
+ * ```typescript
+ * // Server-side configuration loading
+ * import { getConfig } from '@dyanet/nextjs-config-aws';
+ *
+ * const config = await getConfig({
+ *   schema: mySchema,
+ *   aws: { secretName: '/myapp/config' }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Runtime environment variables for client
+ * // In layout.tsx (server component)
+ * import { PublicEnvScript } from '@dyanet/nextjs-config-aws';
+ *
+ * <PublicEnvScript publicVars={['API_URL', 'APP_NAME']} />
+ *
+ * // In client component
+ * import { env } from '@dyanet/nextjs-config-aws';
+ *
+ * const apiUrl = env('API_URL');
+ * ```
+ *
+ * @remarks
+ * For advanced loader access, custom loaders, or direct AWS SDK integration,
+ * import from `@dyanet/config-aws` directly:
+ *
+ * ```typescript
+ * import {
+ *   ConfigManager,
+ *   EnvironmentLoader,
+ *   SecretsManagerLoader,
+ *   SSMParameterStoreLoader,
+ * } from '@dyanet/config-aws';
+ * ```
+ *
+ * @packageDocumentation
  */
-export { ConfigurationError, ValidationError, AWSServiceError, ConfigurationLoadError, MissingConfigurationError, EnvironmentLoader, EnvFileLoader, S3Loader, SecretsManagerLoader, SSMParameterStoreLoader, ConfigManager, ConfigValidationUtil, EnvFileParser, } from '@dyanet/config-aws';
-// Server-side exports
-export { getConfig, clearConfigCache, getConfigCacheSize, invalidateConfig, createConfigProvider, ConfigProvider, useConfig, ConfigContext, } from './server';
-// Components for runtime environment variables
-export { PublicEnvScript, filterEnvVars, generateScriptContent, } from './components';
+// Error classes for error handling
+export { ConfigurationError, ValidationError } from '@dyanet/config-aws';
+// Server-side configuration loading
+export { getConfig } from './server';
+// Component for runtime environment variables
+export { PublicEnvScript } from './components';
 // Client-side environment variable access
-export { env, envFrom, getAllEnv, hasEnv } from './client';
+export { env } from './client';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,yBAAyB,EACzB,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,oBAAoB,EACpB,uBAAuB,EACvB,aAAa,EACb,oBAAoB,EACpB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,sBAAsB;AACtB,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAEhB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,GACd,MAAM,UAAU,CAAC;AAElB,+CAA+C;AAC/C,OAAO,EACL,eAAe,EACf,aAAa,EACb,qBAAqB,GAEtB,MAAM,cAAc,CAAC;AAEtB,0CAA0C;AAC1C,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,mCAAmC;AACnC,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEzE,oCAAoC;AACpC,OAAO,EAAE,SAAS,EAA0B,MAAM,UAAU,CAAC;AAE7D,8CAA8C;AAC9C,OAAO,EAAE,eAAe,EAA6B,MAAM,cAAc,CAAC;AAE1E,0CAA0C;AAC1C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/esm/server/get-config.js

@@ -1,8 +1,35 @@
 /**
  * Server-side configuration loading for Next.js applications.
  * Provides a cached getConfig() function that uses ConfigManager from @dyanet/config-aws.
+ *
+ * This module provides a simplified, opinionated API that hides loader complexity.
+ * For advanced usage such as custom loaders, direct AWS SDK integration, or
+ * fine-grained control over configuration loading, import from `@dyanet/config-aws` directly:
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with custom loaders
+ * import {
+ *   ConfigManager,
+ *   EnvironmentLoader,
+ *   SecretsManagerLoader,
+ *   SSMParameterStoreLoader,
+ * } from '@dyanet/config-aws';
+ *
+ * const manager = new ConfigManager({
+ *   loaders: [
+ *     new EnvironmentLoader({ prefix: 'APP_' }),
+ *     new SecretsManagerLoader({ secretName: '/my-app/config' }),
+ *   ],
+ *   schema: mySchema,
+ * });
+ * await manager.load();
+ * const config = manager.getAll();
+ * ```
  */
 import { ConfigManager, } from '@dyanet/config-aws';
+import { detectEnvironment } from './internal/environment';
+import { createLoaders } from './internal/loader-factory';
 /**
  * Cache storage for configuration
  * Uses a Map to support multiple cache keys (for different option combinations)
@@ -14,15 +41,16 @@ const configCache = new Map();
  */
 let awsApiCallCount = 0;
 /**
- * Generate a cache key from options
+ * Generate a cache key from options.
+ * The cache key is based on aws options, environment, and forceAwsInDev.
  * @internal
  */
-function generateCacheKey(options) {
-    const loaderNames = options.loaders?.map((l) => l.getName()).join(',') ?? '';
-    const precedence = Array.isArray(options.precedence)
-        ? options.precedence.map((p) => `${p.loader}:${p.priority}`).join(',')
-        : options.precedence ?? 'aws-first';
-    return `${loaderNames}|${precedence}`;
+function generateCacheKey(options, resolvedEnvironment) {
+    return JSON.stringify({
+        aws: options.aws,
+        environment: resolvedEnvironment,
+        forceAwsInDev: options.forceAwsInDev ?? false,
+    });
 }
 /**
  * Check if a cache entry is still valid
@@ -36,12 +64,18 @@ function isCacheValid(entry) {
 /**
  * Load configuration for Next.js server-side use.
  *
- * This function provides caching to avoid repeated AWS API calls during request handling.
- * Configuration is cached based on the loader configuration and precedence strategy.
+ * This function provides automatic environment detection and caching to avoid
+ * repeated AWS API calls during request handling. Configuration is cached based
+ * on the AWS options, environment, and forceAwsInDev setting.
+ *
+ * Environment Behavior:
+ * - development: env vars + .env.local/.env files, AWS only if forceAwsInDev
+ * - production: env vars + .env file + AWS sources (if configured)
+ * - test: env vars only (no file or AWS access)
  *
  * @example
  * ```typescript
- * import { getConfig, EnvironmentLoader, SecretsManagerLoader } from '@dyanet/nextjs-config-aws';
+ * import { getConfig } from '@dyanet/nextjs-config-aws';
  * import { z } from 'zod';
  *
  * const schema = z.object({
@@ -49,29 +83,34 @@ function isCacheValid(entry) {
  *   API_KEY: z.string(),
  * });
  *
- * // In a Server Component or API route
- * export default async function Page() {
- *   const config = await getConfig({
- *     schema,
- *     loaders: [
- *       new EnvironmentLoader(),
- *       new SecretsManagerLoader({ secretName: '/my-app/config' }),
- *     ],
- *     precedence: 'aws-first',
- *   });
+ * // Minimal usage - auto-detects environment
+ * const config = await getConfig({ schema });
  *
- *   return <div>DB: {config.DATABASE_URL}</div>;
- * }
+ * // With AWS Secrets Manager (loaded in production)
+ * const config = await getConfig({
+ *   schema,
+ *   aws: { secretName: '/my-app/config', region: 'us-east-1' }
+ * });
+ *
+ * // Force AWS in development for testing
+ * const config = await getConfig({
+ *   schema,
+ *   aws: { secretName: '/my-app/config' },
+ *   forceAwsInDev: true
+ * });
  * ```
  *
  * @param options Configuration options
  * @returns Promise resolving to the validated configuration object
+ * @throws {ValidationError} When schema validation fails (includes invalid key names)
  */
 export async function getConfig(options = {}) {
-    const { schema, loaders = [], precedence = 'aws-first', cache = true, cacheTTL = 60000, // 1 minute default
+    const { schema, aws, environment: explicitEnvironment, forceAwsInDev = false, cache = true, cacheTTL = 60000, // 1 minute default
     enableLogging = false, } = options;
-    // Generate cache key
-    const cacheKey = generateCacheKey(options);
+    // Determine environment: explicit option takes precedence over auto-detection
+    const resolvedEnvironment = explicitEnvironment ?? detectEnvironment();
+    // Generate cache key based on aws options, environment, and forceAwsInDev
+    const cacheKey = generateCacheKey(options, resolvedEnvironment);
     // Check cache if enabled
     if (cache) {
         const cached = configCache.get(cacheKey);
@@ -81,11 +120,17 @@ export async function getConfig(options = {}) {
     }
     // Increment API call counter (for testing)
     awsApiCallCount++;
-    // Create ConfigManager with provided options
+    // Create loaders using the internal factory
+    const loaders = createLoaders({
+        environment: resolvedEnvironment,
+        aws,
+        forceAwsInDev,
+    });
+    // Create ConfigManager with generated loaders
     const managerOptions = {
         loaders,
         schema,
-        precedence,
+        precedence: 'aws-first',
         validateOnLoad: true,
         enableLogging,
     };
@@ -139,7 +184,8 @@ export function resetAwsApiCallCount() {
  * @param options The options used to create the cache entry
  */
 export function invalidateConfig(options) {
-    const cacheKey = generateCacheKey(options);
+    const resolvedEnvironment = options.environment ?? detectEnvironment();
+    const cacheKey = generateCacheKey(options, resolvedEnvironment);
     configCache.delete(cacheKey);
 }
 //# sourceMappingURL=get-config.js.map

package/dist/esm/server/get-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-config.js","sourceRoot":"","sources":["../../../src/server/get-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"get-config.js","sourceRoot":"","sources":["../../../src/server/get-config.ts"],"names":[],"mappings":"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"}

package/dist/esm/server/internal/environment.js

@@ -0,0 +1,35 @@
+/**
+ * Environment detection utilities for Next.js configuration.
+ * @internal
+ */
+/**
+ * Detect the current environment mode based on NODE_ENV.
+ *
+ * @returns The detected environment mode:
+ *   - 'production' if NODE_ENV is 'production'
+ *   - 'test' if NODE_ENV is 'test'
+ *   - 'development' for all other cases (including undefined)
+ *
+ * @example
+ * ```typescript
+ * // NODE_ENV=production
+ * detectEnvironment(); // 'production'
+ *
+ * // NODE_ENV=test
+ * detectEnvironment(); // 'test'
+ *
+ * // NODE_ENV=development or undefined
+ * detectEnvironment(); // 'development'
+ * ```
+ */
+export function detectEnvironment() {
+    const nodeEnv = process.env['NODE_ENV'];
+    if (nodeEnv === 'production') {
+        return 'production';
+    }
+    if (nodeEnv === 'test') {
+        return 'test';
+    }
+    return 'development';
+}
+//# sourceMappingURL=environment.js.map

package/dist/esm/server/internal/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../../src/server/internal/environment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAExC,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;QAC7B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}