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

package/dist/types/server/get-config.d.ts

@@ -1,35 +1,110 @@
 /**
  * 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 type { ZodType } from 'zod';
-import { ConfigLoader, PrecedenceStrategy } from '@dyanet/config-aws';
+import { EnvironmentMode } from './internal/environment';
+import { AwsOptions } from './internal/loader-factory';
 /**
- * Options for Next.js configuration loading
+ * Options for Next.js configuration loading.
+ *
+ * This interface provides a simplified, opinionated API that hides loader complexity
+ * and provides automatic environment detection.
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage - just schema
+ * const config = await getConfig({ schema: mySchema });
+ *
+ * // With AWS Secrets Manager
+ * const config = await getConfig({
+ *   schema: mySchema,
+ *   aws: { secretName: '/myapp/config' }
+ * });
+ *
+ * // Force AWS in development
+ * const config = await getConfig({
+ *   schema: mySchema,
+ *   aws: { secretName: '/myapp/config' },
+ *   forceAwsInDev: true
+ * });
+ * ```
  */
 export interface NextConfigOptions<T = Record<string, unknown>> {
     /** Zod schema for validation */
     schema?: ZodType<T>;
-    /** Array of loaders to use */
-    loaders?: ConfigLoader[];
-    /** Precedence strategy for merging configurations */
-    precedence?: PrecedenceStrategy;
-    /** Enable caching. Default: true */
+    /**
+     * AWS configuration options.
+     * When provided, enables loading from AWS services based on environment.
+     */
+    aws?: AwsOptions;
+    /**
+     * Override environment detection ('development' | 'production' | 'test').
+     * When provided, this takes precedence over NODE_ENV auto-detection.
+     */
+    environment?: EnvironmentMode;
+    /**
+     * Force AWS loading even in development mode.
+     * By default, AWS sources are only loaded in production.
+     * @default false
+     */
+    forceAwsInDev?: boolean;
+    /**
+     * Enable caching.
+     * @default true
+     */
     cache?: boolean;
-    /** Cache TTL in milliseconds. Default: 60000 (1 minute) */
+    /**
+     * Cache TTL in milliseconds.
+     * @default 60000 (1 minute)
+     */
     cacheTTL?: number;
-    /** Enable logging. Default: false */
+    /**
+     * Enable logging.
+     * @default false
+     */
     enableLogging?: boolean;
 }
 /**
  * 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({
@@ -37,23 +112,26 @@ export interface NextConfigOptions<T = Record<string, unknown>> {
  *   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 declare function getConfig<T = Record<string, unknown>>(options?: NextConfigOptions<T>): Promise<T>;
 /**

package/dist/types/server/get-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-config.d.ts","sourceRoot":"","sources":["../../../src/server/get-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,EAEL,YAAY,EAEZ,kBAAkB,EAEnB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,gCAAgC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,qDAAqD;IACrD,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAkDZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAGvE"}
+{"version":3,"file":"get-config.d.ts","sourceRoot":"","sources":["../../../src/server/get-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAMnC,OAAO,EAAqB,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EAAiB,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,gCAAgC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEpB;;;OAGG;IACH,GAAG,CAAC,EAAE,UAAU,CAAC;IAEjB;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAE9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CA6DZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAIvE"}

package/dist/types/server/index.d.ts

@@ -1,6 +1,13 @@
 /**
  * Server-side exports for Next.js configuration management.
+ *
+ * This module exports React-free configuration utilities that work in all
+ * server contexts including API routes, middleware, and server components.
+ *
+ * For React context providers (ConfigProvider, useConfig), import from
+ * '@dyanet/nextjs-config-aws/react' instead.
  */
 export { getConfig, clearConfigCache, getConfigCacheSize, invalidateConfig, type NextConfigOptions, } from './get-config';
-export { createConfigProvider, ConfigProvider, useConfig, ConfigContext, } from './config-provider';
+export type { AwsOptions } from './internal/loader-factory';
+export type { EnvironmentMode } from './internal/environment';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,GACd,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/types/server/internal/environment.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment detection utilities for Next.js configuration.
+ * @internal
+ */
+/**
+ * Supported environment modes for configuration loading.
+ */
+export type EnvironmentMode = 'development' | 'production' | 'test';
+/**
+ * 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 declare function detectEnvironment(): EnvironmentMode;
+//# sourceMappingURL=environment.d.ts.map

package/dist/types/server/internal/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../../src/server/internal/environment.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,YAAY,GAAG,MAAM,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,IAAI,eAAe,CAYnD"}

package/dist/types/server/internal/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Internal utilities for Next.js configuration.
+ * These are not exported from the public API.
+ * @internal
+ */
+export { detectEnvironment, type EnvironmentMode } from './environment';
+export { createLoaders, type LoaderFactoryOptions } from './loader-factory';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/server/internal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/server/internal/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/types/server/internal/loader-factory.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Internal loader factory for Next.js configuration.
+ * Creates loaders based on environment and options.
+ * @internal
+ */
+import { ConfigLoader } from '@dyanet/config-aws';
+import { EnvironmentMode } from './environment';
+/**
+ * AWS configuration options for the loader factory.
+ */
+export interface AwsOptions {
+    /** Secret name for AWS Secrets Manager */
+    secretName?: string;
+    /** Parameter path prefix for SSM Parameter Store */
+    ssmPrefix?: string;
+    /** AWS region (defaults to AWS_REGION env var) */
+    region?: string;
+}
+/**
+ * Options for the loader factory.
+ */
+export interface LoaderFactoryOptions {
+    /** The environment mode to use for loader selection */
+    environment: EnvironmentMode;
+    /** AWS configuration options */
+    aws?: AwsOptions;
+    /** Force AWS loading even in development mode */
+    forceAwsInDev?: boolean;
+}
+/**
+ * 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
+ */
+export declare function createLoaders(options: LoaderFactoryOptions): ConfigLoader[];
+//# sourceMappingURL=loader-factory.d.ts.map

package/dist/types/server/internal/loader-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-factory.d.ts","sourceRoot":"","sources":["../../../../src/server/internal/loader-factory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,YAAY,EAKb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,WAAW,EAAE,eAAe,CAAC;IAC7B,gCAAgC;IAChC,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,EAAE,CAmC3E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dyanet/nextjs-config-aws",
-  "version": "1.0.0-beta.1",
+  "version": "1.1.0",
   "description": "Next.js adapter for AWS configuration management with support for server components, runtime environment variables, and AWS services integration",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -10,6 +10,11 @@
       "import": "./dist/esm/index.js",
       "require": "./dist/cjs/index.js",
       "types": "./dist/types/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/esm/react.js",
+      "require": "./dist/cjs/react.js",
+      "types": "./dist/types/react.d.ts"
     }
   },
   "files": [
@@ -49,8 +54,8 @@
   "author": "Dyanet",
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0",
-    "npm": ">=8.0.0"
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
   },
   "publishConfig": {
     "access": "public",
@@ -74,7 +79,7 @@
     "jest": "^29.5.0",
     "next": "^16.0.0",
     "react": "^19.0.0",
-    "rimraf": "^5.0.0",
+    "rimraf": "^6.0.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.9.2",
     "zod": "^3.22.0"