✨ Add enum parser for type-safe environment variable validation

Introduce envParsers.enum() to validate environment variables against a
set of allowed values with full type safety. The parser supports:

- Generic type parameter for compile-time type inference
- Optional default values that fall back when undefined
- Clear error messages listing allowed values
- Isomorphic operation (server and client contexts)

Update README and MIGRATION docs to document the new parser alongside
other v4.x features including default values, requireEnv(), and the
existing parsers (boolean, number, array, json, url).

Author: hyperb1iss

README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Next.js](https://img.shields.io/badge/Next.js%2015-e135ff.svg?style=for-the-badge&logo=next.js&logoColor=white)](https://nextjs.org/)
+[![Next.js](https://img.shields.io/badge/Next.js%2015%20%7C%2016-e135ff.svg?style=for-the-badge&logo=next.js&logoColor=white)](https://nextjs.org/)
 [![React](https://img.shields.io/badge/React%2019-80ffea.svg?style=for-the-badge&logo=react&logoColor=white)](https://react.dev/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ff79c6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/badge/License-MIT-f1fa8c?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](https://opensource.org/licenses/MIT)
@@ -25,9 +25,11 @@
 ## ✨ Highlights
 
 - **Isomorphic Design:** Works seamlessly on both server and browser, and even in middleware
-- **Next.js 15 & React 19 Ready:** Fully compatible with the latest Next.js features including async server components
+- **Next.js 15/16 & React 19 Ready:** Fully compatible with the latest Next.js features including async server
+  components
 - **`.env` Friendly:** Use `.env` files during development, just like standard Next.js
-- **Type-Safe:** Full TypeScript support for environment variables
+- **Type-Safe Parsers:** Convert environment strings to booleans, numbers, arrays, JSON, URLs, and enums
+- **Secure by Default:** XSS protection via JSON escaping, immutable runtime values with `Object.freeze`
 - **Zero Config:** Works out of the box with sensible defaults
 
 ## 🤔 Why `next-runtime-env`?
@@ -170,6 +172,76 @@ export const config = {
 > **Note:** The `env()` function works in all Next.js contexts - server components, client components, API routes, and
 > middleware. It's safe to use everywhere and provides a consistent API across your application.
 
+### Default Values
+
+The `env()` function accepts an optional default value:
+
+```tsx
+import { env } from '@hyperb1iss/next-runtime-env'
+
+// Returns 'https://api.default.com' if NEXT_PUBLIC_API_URL is undefined
+const apiUrl = env('NEXT_PUBLIC_API_URL', 'https://api.default.com')
+
+// Default values work in all contexts (client, server, middleware)
+const timeout = env('NEXT_PUBLIC_TIMEOUT', '5000')
+```
+
+### Required Environment Variables
+
+Use `requireEnv()` when a variable must be defined:
+
+```tsx
+import { requireEnv } from '@hyperb1iss/next-runtime-env'
+
+// Throws descriptive error if NEXT_PUBLIC_API_URL is undefined
+const apiUrl = requireEnv('NEXT_PUBLIC_API_URL')
+// Error: "Required environment variable 'NEXT_PUBLIC_API_URL' is not defined."
+```
+
+### Type-Safe Parsers
+
+Use `envParsers` to convert environment strings to typed values:
+
+```tsx
+import { envParsers } from '@hyperb1iss/next-runtime-env'
+
+// Boolean - recognizes 'true', '1', 'yes', 'on' (case-insensitive)
+const debug = envParsers.boolean('NEXT_PUBLIC_DEBUG') // false by default
+const enabled = envParsers.boolean('NEXT_PUBLIC_FEATURE', true) // custom default
+
+// Number - integers and floats
+const port = envParsers.number('NEXT_PUBLIC_PORT', 3000)
+const ratio = envParsers.number('NEXT_PUBLIC_RATIO', 1.0)
+
+// Array - comma-separated values (trims whitespace, filters empty)
+const features = envParsers.array('NEXT_PUBLIC_FEATURES')
+// 'auth, payments, analytics' → ['auth', 'payments', 'analytics']
+
+// JSON - parse complex objects
+interface Config {
+    api: string
+    timeout: number
+}
+const config = envParsers.json<Config>('NEXT_PUBLIC_CONFIG')
+
+// URL - validates and returns URL string
+const apiUrl = envParsers.url('NEXT_PUBLIC_API_URL')
+const cdn = envParsers.url('NEXT_PUBLIC_CDN', 'https://cdn.default.com')
+
+// Enum - restrict to allowed values with type safety
+type Environment = 'development' | 'staging' | 'production'
+const appEnv = envParsers.enum<Environment>(
+    'NEXT_PUBLIC_ENV',
+    ['development', 'staging', 'production'],
+    'development', // default value
+)
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+const logLevel = envParsers.enum<LogLevel>('NEXT_PUBLIC_LOG_LEVEL', ['debug', 'info', 'warn', 'error'])
+```
+
+All parsers work isomorphically (server and client) and provide clear error messages for invalid values.
+
 ## 🛠 Advanced Usage
 
 ### Exposing Non-Prefixed Variables
@@ -268,6 +340,16 @@ For static exports with runtime environment support:
 
 ## 🔒 Security Considerations
 
+### Built-in Security Features
+
+This library includes multiple layers of security by default:
+
+- **XSS Protection:** All environment values are JSON-escaped before injection, preventing script injection attacks
+- **Immutable Runtime Values:** Environment values are wrapped with `Object.freeze()`, preventing modification after
+  initialization
+- **Strict Prefix Enforcement:** Only `NEXT_PUBLIC_*` variables are exposed to the browser; accessing private variables
+  throws an error
+
 ### Never Expose Secrets to the Browser
 
 **Critical:** Only variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Never expose sensitive data:
@@ -286,10 +368,15 @@ export async function getData() {
 
 ### Environment Variable Validation
 
-Validate required environment variables at build time:
+Use `requireEnv()` for required variables, or validate multiple at once:
 
 ```tsx
-// lib/env.ts
+// Using requireEnv() - throws if undefined
+import { requireEnv } from '@hyperb1iss/next-runtime-env'
+
+const apiUrl = requireEnv('NEXT_PUBLIC_API_URL')
+
+// Validating multiple variables
 import { env } from '@hyperb1iss/next-runtime-env'
 
 export function validateEnv() {
@@ -301,9 +388,6 @@ export function validateEnv() {
         }
     }
 }
-
-// Call in your app initialization
-validateEnv()
 ```
 
 ### Content Security Policy

docs/MIGRATION.md

@@ -87,6 +87,51 @@ The migration from the original `next-runtime-env@3.x` to `@hyperb1iss/next-runt
 
 All existing code using the library will continue to work without modification.
 
+## New Features in v4.x
+
+v4.x adds several new features while maintaining backwards compatibility:
+
+### Default Values
+
+The `env()` function now accepts an optional default value:
+
+```tsx
+import { env } from '@hyperb1iss/next-runtime-env'
+
+const apiUrl = env('NEXT_PUBLIC_API_URL', 'https://api.default.com')
+```
+
+### Required Environment Variables
+
+Use `requireEnv()` for variables that must be defined:
+
+```tsx
+import { requireEnv } from '@hyperb1iss/next-runtime-env'
+
+// Throws if undefined
+const apiUrl = requireEnv('NEXT_PUBLIC_API_URL')
+```
+
+### Type-Safe Parsers
+
+Convert environment strings to typed values:
+
+```tsx
+import { envParsers } from '@hyperb1iss/next-runtime-env'
+
+const debug = envParsers.boolean('NEXT_PUBLIC_DEBUG')
+const port = envParsers.number('NEXT_PUBLIC_PORT', 3000)
+const features = envParsers.array('NEXT_PUBLIC_FEATURES')
+const config = envParsers.json<Config>('NEXT_PUBLIC_CONFIG')
+const apiUrl = envParsers.url('NEXT_PUBLIC_API_URL')
+const appEnv = envParsers.enum('NEXT_PUBLIC_ENV', ['development', 'staging', 'production'])
+```
+
+### Enhanced Security
+
+- **XSS Protection:** All injected values are JSON-escaped
+- **Immutability:** Runtime values are wrapped with `Object.freeze()`
+
 ## Upgrading to Next.js 15 (Additional Steps)
 
 If you're upgrading from Next.js 14 to Next.js 15 as part of this migration, you may need to update custom code that
@@ -145,11 +190,11 @@ export function getCustomEnv() {
 
 ### What Changed Under the Hood
 
-The library now uses Next.js 15's stable dynamic rendering APIs:
+The library now uses Next.js 15/16's stable dynamic rendering APIs:
 
-- `PublicEnvScript` and `PublicEnvProvider` use `await connection()`
-- The `env()` utility uses `headers()` to force dynamic rendering
-- All components are now async server components (React handles this automatically)
+- `PublicEnvScript` and `EnvScript` use `headers()` for nonce retrieval (when configured)
+- The `env()` utility reads from `process.env` (server) or `window.__ENV` (client) directly
+- Script injection includes XSS protection and `Object.freeze()` for immutability
 
 ### Troubleshooting
 
@@ -204,9 +249,9 @@ If you're still using the original `next-runtime-env@1.x` with the Pages Router:
 
 ### This Fork (Maintained)
 
-| Package                      | Version | Next.js | React | Notes                                       |
-| ---------------------------- | ------- | ------- | ----- | ------------------------------------------- |
-| @hyperb1iss/next-runtime-env | 4.x     | 15.x    | 19.x  | Next.js 15 & React 19 with async components |
+| Package                      | Version | Next.js    | React | Notes                                          |
+| ---------------------------- | ------- | ---------- | ----- | ---------------------------------------------- |
+| @hyperb1iss/next-runtime-env | 4.x     | 15.x, 16.x | 19.x  | Next.js 15/16 & React 19 with async components |
 
 ### Original Project (Unmaintained)
 

src/script/parsers.spec.ts

@@ -207,4 +207,56 @@ describe('envParsers', () => {
             expect(envParsers.url('NEXT_PUBLIC_API_URL')).toBe('https://api.example.com')
         })
     })
+
+    describe('enum()', () => {
+        const environments = ['development', 'staging', 'production'] as const
+
+        it('should return valid enum value', () => {
+            process.env.NEXT_PUBLIC_ENV = 'production'
+            expect(envParsers.enum('NEXT_PUBLIC_ENV', environments)).toBe('production')
+        })
+
+        it('should return default when undefined', () => {
+            expect(envParsers.enum('NEXT_PUBLIC_MISSING', environments, 'development')).toBe('development')
+        })
+
+        it('should throw when undefined with no default', () => {
+            expect(() => envParsers.enum('NEXT_PUBLIC_MISSING', environments)).toThrow(
+                "Required environment variable 'NEXT_PUBLIC_MISSING' is not defined",
+            )
+        })
+
+        it('should throw for invalid enum value', () => {
+            process.env.NEXT_PUBLIC_ENV = 'invalid'
+            expect(() => envParsers.enum('NEXT_PUBLIC_ENV', environments)).toThrow(
+                "Environment variable 'NEXT_PUBLIC_ENV' has invalid value: 'invalid'",
+            )
+        })
+
+        it('should list allowed values in error message', () => {
+            process.env.NEXT_PUBLIC_ENV = 'invalid'
+            expect(() => envParsers.enum('NEXT_PUBLIC_ENV', environments)).toThrow(
+                "Expected one of: 'development', 'staging', 'production'",
+            )
+        })
+
+        it('should work with two-value enums', () => {
+            const booleanLike = ['enabled', 'disabled'] as const
+            process.env.NEXT_PUBLIC_FEATURE = 'enabled'
+            expect(envParsers.enum('NEXT_PUBLIC_FEATURE', booleanLike)).toBe('enabled')
+        })
+
+        it('should work in browser context', () => {
+            mockWindow({ NEXT_PUBLIC_ENV: 'staging' })
+            expect(envParsers.enum('NEXT_PUBLIC_ENV', environments)).toBe('staging')
+        })
+
+        it('should be type-safe with generic', () => {
+            type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+            const levels: readonly LogLevel[] = ['debug', 'info', 'warn', 'error']
+            process.env.NEXT_PUBLIC_LOG_LEVEL = 'warn'
+            const result: LogLevel = envParsers.enum<LogLevel>('NEXT_PUBLIC_LOG_LEVEL', levels)
+            expect(result).toBe('warn')
+        })
+    })
 })

src/script/parsers.ts

@@ -194,4 +194,58 @@ export const envParsers = {
             )
         }
     },
+
+    /**
+     * Parses an environment variable as one of a set of allowed values.
+     *
+     * Provides type-safe enum-like validation for environment variables
+     * that should only contain specific string values.
+     *
+     * @param key - The environment variable name
+     * @param allowedValues - Array of valid string values
+     * @param defaultValue - Default value if undefined (must be in allowedValues)
+     * @returns The validated enum value
+     *
+     * @throws {Error} If the value is not in the allowed values list
+     * @throws {Error} If the value is undefined and no default is provided
+     *
+     * @example
+     * ```ts
+     * // NEXT_PUBLIC_ENV=production
+     * type Environment = 'development' | 'staging' | 'production';
+     * const appEnv = envParsers.enum<Environment>(
+     *   'NEXT_PUBLIC_ENV',
+     *   ['development', 'staging', 'production'],
+     *   'development'
+     * );
+     *
+     * // NEXT_PUBLIC_LOG_LEVEL=debug
+     * type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+     * const logLevel = envParsers.enum<LogLevel>(
+     *   'NEXT_PUBLIC_LOG_LEVEL',
+     *   ['debug', 'info', 'warn', 'error']
+     * );
+     * ```
+     */
+    enum<T extends string>(key: string, allowedValues: readonly T[], defaultValue?: T): T {
+        const value = env(key)
+        if (value === undefined) {
+            if (defaultValue === undefined) {
+                throw new Error(
+                    `Required environment variable '${key}' is not defined.\n` +
+                        `Expected one of: ${allowedValues.map((v) => `'${v}'`).join(', ')}.`,
+                )
+            }
+            return defaultValue
+        }
+
+        if (!allowedValues.includes(value as T)) {
+            throw new Error(
+                `Environment variable '${key}' has invalid value: '${value}'.\n` +
+                    `Expected one of: ${allowedValues.map((v) => `'${v}'`).join(', ')}.`,
+            )
+        }
+
+        return value as T
+    },
 } as const