envapt 2.1.1 → 2.2.1

package/README.md

@@ -3,8 +3,8 @@
 </p>
 
 <p align="center">
-  A TypeScript environment configuration library that eliminates the boilerplate of transforming parsed <code>.env</code><br/>
-  Get environment variables with correct runtime typing and fallbacks, template support, and automatic, built-in, & custom transformations.<br/>
+  A JavaScript/TypeScript environment configuration library that eliminates the boilerplate of transforming parsed <code>.env</code><br/>
+  Get environment variables with correct runtime typing and fallbacks, template support, and automatic, built-in, & custom transformations, and tagged template resolver.<br/>
   <strong>No more <code>process.env.PORT || '3000'</code> everywhere!</strong>
 </p>
 <div align="center">
@@ -27,12 +27,13 @@
 
 - 🔧 **Automatic Type Detection** - Runtime types inferred from fallback values
 - 🔗 **Template Variables** - `${VAR}` syntax with circular reference protection
-- 🎯 **Class Properties** - Functional and Decorator-based configuration for class members
+- 🎯 **Class Properties** - Functional and Decorator-based configuration for class members _(Decorators: TypeScript only)_
 - 🏷️ **Built-in & Custom Converters** - Ready-to-use converters for common patterns + custom transformations
+- 🔖 **Tagged Template Resolver** - Tagged template literals with environment variable resolution
 - 🌍 **Environment Detection** - Built-in development/staging/production handling
-- 📂 **Multiple .env Files** - Load from multiple sources
 - 💪 **Edge Case Handling** - Robust validation and parsing for all scenarios
-- 🛡️ **Type Safety** - Full TypeScript support with proper type inference
+- 🛡️ **Type Safety** - Full TypeScript support with proper type inference _(TypeScript optional)_
+- 📂 **Multiple .env Files** - Load from multiple sources
 - ⚡ **Lightweight** - Minimal overhead with [`dotenv`](https://www.npmjs.com/package/dotenv) bundled
 
 ---
@@ -59,6 +60,7 @@
     - [Custom Converters](#custom-converters)
     - [Handling Missing Values](#handling-missing-values)
   - [Functional API](#functional-api)
+  - [Tagged Template Resolver](#tagged-template-resolver)
   - [Converter Type Quick Reference](#converter-type-quick-reference)
 
 ### 🌍 Environment & Templates
@@ -79,7 +81,8 @@
 ### 🚀 Examples
 
 - [Advanced Examples](#advanced-examples)
-  - [Complex Configuration](#complex-configuration)
+  - [JavaScript](#javascript)
+  - [TypeScript](#typescript)
 
 ---
 
@@ -90,16 +93,16 @@
 - **Node.js**: `>=22.0.0`  
   _Recommended for full ESM and `nodenext` support_
 
-- **TypeScript**: `>=5.8`
-
 #### 📦 Runtime Dependency
 
 - **dotenv**: _(bundled at runtime)_
 
-#### 🛠️ TypeScript Compiler Options
+#### 🛠️ TypeScript Users Only
+
+- **TypeScript**: `>=5.8` _(Only required for decorator API)_
 
 ```jsonc
-// tsconfig.json (required settings)
+// tsconfig.json (required settings for decorators)
 {
   "experimentalDecorators": true,
   "module": "esnext", // or "nodenext"
@@ -109,6 +112,9 @@
 }
 ```
 
+> [!NOTE]
+> **JavaScript users** can use all features except the `@Envapt` decorator API. The [Functional API](#functional-api), [Tagged Template Resolver](#tagged-template-resolver), and all converters work perfectly in plain JavaScript.
+
 ## Quick Start
 
 ### Installation
@@ -132,7 +138,29 @@ MAX_CONNECTIONS=100
 ALLOWED_ORIGINS=https://app.com,https://admin.com
 ```
 
-Use with decorators:
+**JavaScript Example (Functional API):**
+
+```js
+import { Envapter, Converters } from 'envapt';
+
+// Basic usage
+const port = Envapter.getNumber('APP_PORT', 3000);
+const url = Envapter.get('APP_URL', 'http://localhost:3000');
+const isProduction = Envapter.isProduction;
+
+console.log(`Server running on port ${port}`); // 8443
+console.log(`URL: ${url}`); // "http://localhost:8443"
+
+// Advanced converters
+const corsOrigins = Envapter.getUsing('ALLOWED_ORIGINS', Converters.Array, []);
+const dbConfig = Envapter.getUsing('DATABASE_CONFIG', Converters.Json, {});
+
+// Tagged template literals
+const message = Envapter.resolve`Server ${'APP_URL'} is ready!`;
+console.log(message); // "Server http://localhost:8443 is ready!"
+```
+
+**TypeScript Example (Decorator API):**
 
 ```ts
 import { Envapt, Envapter, Converters } from 'envapt';
@@ -171,30 +199,23 @@ class DatabaseService {
 
 // Usage
 console.log(AppConfig.port); // 8443 (number)
-console.log(AppConfig.url.href); // "http://localhost:8443" (templated!)
+console.log(AppConfig.url.href); // "http://localhost:8443"
 
 const dbService = new DatabaseService();
 await dbService.connect();
 ```
 
-Or use functionally:
-
-```ts
-import { Envapter } from 'envapt';
-
-const port = Envapter.getNumber('APP_PORT', 3000);
-const url = Envapter.get('APP_URL', 'http://localhost:3000');
-const isProduction = Envapter.getBoolean('IS_PRODUCTION', false);
-```
-
 ## API Reference
 
 ### Decorator API
 
+> [!IMPORTANT]
+> **TypeScript Only**: The `@Envapt` decorator API requires TypeScript with `experimentalDecorators: true`. JavaScript users should use the [Functional API](#functional-api) instead.
+
 The `@Envapt` decorator can be used on both **static** and **instance** class properties:
 
-- **Static properties**: Use for global configuration that's shared across your entire application (e.g., app port, global features, environment settings)
-- **Instance properties**: Use for service-specific configuration that may vary per service or when you want the configuration tied to a specific class instance (e.g., database connections, service endpoints, per-service settings)
+- **Static properties**: Can use for global configuration that's shared across your entire application (e.g., app port, global features, environment settings)
+- **Instance properties**: Can use for service-specific configuration that may vary per service or when you want the configuration tied to a specific class instance (e.g., database connections, service endpoints, per-service settings)
 
 **Important**: Instance properties must be declared with `declare` keyword or `!` assertion since they're populated by the decorator rather than set in a constructor.
 
@@ -471,9 +492,9 @@ class Config extends Envapter {
 
 ### Functional API
 
-For functional-style environment variable on primitive types:
+For functional-style environment variable access on primitive types:
 
-```ts
+```js
 import { Envapter, Converters } from 'envapt';
 
 // Basic type-specific getters
@@ -496,12 +517,14 @@ const processed = envapter.getUsing('DATA', Converters.Array);
 
 For functional-style environment variable access with converters:
 
-```ts
+```js
 import { Envapter, Converters } from 'envapt';
 
 // Use built-in converters directly
 const config = Envapter.getUsing('API_CONFIG', Converters.Json, { default: 'value' });
 const urls = Envapter.getUsing('SERVICE_URLS', { delimiter: '|', type: Converters.Url });
+
+// TypeScript: Use type override for better type inference
 const typedConfig = Envapter.getUsing<{ host: string; port: number; ssl: boolean }>('DATABASE_CONFIG', Converters.Json);
 // typedConfig is now typed as { host: string; port: number; ssl: boolean } instead of JsonValue | undefined
 
@@ -557,6 +580,50 @@ const result = envapter.getUsing('DATABASE_CONFIG', Converters.Json);
 > [!TIP]
 > **Use the `Converters` enum**. They look better. Start with built-in converters, use primitive constructors when you need coercion, and custom converters for complex transforms.
 
+### Tagged Template Resolver
+
+Envapt provides a convenient tagged template literal syntax for resolving environment variables directly in template strings:
+
+```js
+import { Envapter } from 'envapt';
+
+// Given these environment variables:
+// API_HOST=api.example.com
+// API_PORT=8080
+// API_URL=https://${API_HOST}:${API_PORT}
+// SERVICE_NAME=UserService
+
+// Use tagged template literals for string interpolation
+const endpoint = Envapter.resolve`Connecting to ${'SERVICE_NAME'} at ${'API_URL'}`;
+// Returns: "Connecting to UserService at https://api.example.com:8080"
+
+const logMessage = Envapter.resolve`Starting ${'SERVICE_NAME'} on port ${'API_PORT'}`;
+// Returns: "Starting UserService on port 8080"
+
+// Works with instance methods too
+const envapter = new Envapter();
+const status = envapter.resolve`${'SERVICE_NAME'} is running`;
+// Returns: "UserService is running"
+```
+
+Works seamlessly with template variables in your `.env` file:
+
+```env
+# Your .env file
+API_HOST=api.example.com
+API_PORT=8080
+API_URL=https://${API_HOST}:${API_PORT}  # Template resolved first
+SERVICE_NAME=UserService
+```
+
+```ts
+const message = Envapter.resolve`Service ${'SERVICE_NAME'} endpoint: ${'API_URL'}`;
+// Returns: "Service UserService endpoint: https://api.example.com:8080"
+```
+
+> [!NOTE]
+> Tagged template literals work with any environment variables, including those that use `${VAR}` template syntax in your `.env` file. The template resolution happens first, then the tagged template interpolation.
+
 ## Environment Detection
 
 Envapt automatically detects your environment from these variables (in order):
@@ -569,7 +636,7 @@ Supported values: `development`, `staging`, `production` (case-sensitive)
 
 ### Environment Management
 
-```ts
+```js
 import { Envapter, EnvaptEnvironment } from 'envapt';
 
 // Check current environment
@@ -587,7 +654,7 @@ Envapter.environment = 'staging'; // string also works
 
 ### Multiple .env Files
 
-```ts
+```js
 import { resolve } from 'node:path';
 import { Envapter } from 'envapt';
 
@@ -604,7 +671,7 @@ Envapter.envPaths = resolve(__dirname, '.env.production');
 
 Envapt allows you to customize dotenv behavior by setting configuration options:
 
-```ts
+```js
 import { Envapter } from 'envapt';
 
 // Set dotenv configuration options
@@ -650,7 +717,7 @@ Circular references are detected and preserved as-is rather than causing infinit
 
 Envapt provides detailed error codes for better debugging and error handling:
 
-```ts
+```js
 import { EnvaptError, EnvaptErrorCodes } from 'envapt';
 
 try {
@@ -708,7 +775,46 @@ try {
 
 ## Advanced Examples
 
-### Complex Configuration
+### JavaScript
+
+```js
+import { Envapter, Converters } from 'envapt';
+
+// Global configuration
+const config = {
+  port: Envapter.getNumber('PORT', 3000),
+  requestTimeout: Envapter.getUsing('REQUEST_TIMEOUT', Converters.Time, 10000), // "5s" -> 5000ms
+  featureFlags: Envapter.getWith(
+    'FEATURE_FLAGS',
+    (raw, fallback) => {
+      if (!raw) return fallback;
+      return new Set(raw.split(',').map((s) => s.trim()));
+    },
+    new Set(['basic'])
+  )
+};
+
+// Service configuration
+class DatabaseService {
+  constructor() {
+    this.databaseUrl = Envapter.get('DB_URL', 'sqlite://memory');
+    this.cacheTtl = Envapter.getUsing('CACHE_TTL', Converters.Time, 3600000); // "1h" -> 3600000ms
+    this.redisUrls = Envapter.getWith(
+      'REDIS_URLS',
+      (raw, fallback) => (raw ? raw.split(',').map((s) => new URL(s)) : fallback),
+      [new URL('redis://localhost:6379')]
+    );
+  }
+
+  async initialize() {
+    console.log(`App running on port ${config.port}`);
+    console.log(`Database: ${this.databaseUrl}`);
+    console.log(`Cache TTL: ${this.cacheTtl}ms`);
+  }
+}
+```
+
+### TypeScript
 
 ```ts
 import { Envapt, Envapter, Converters } from 'envapt';

package/dist/index.cjs

@@ -788,17 +788,46 @@ var AdvancedMethods = class _AdvancedMethods extends PrimitiveMethods {
 };
 
 // src/Envapter.ts
-var Envapter = class extends AdvancedMethods {
+var Envapter = class _Envapter extends AdvancedMethods {
   static {
     __name(this, "Envapter");
   }
+  /**
+   * Tagged template literal for resolving environment variables in template strings.
+   *
+   * @example
+   * ```ts
+   * // Given API_HOST=api.example.com and API_PORT=8080 in environment
+   * const endpoint = Envapter.resolve`Connecting to ${'API_HOST'}:${'API_PORT'}`;
+   * // Returns: "Connecting to api.example.com:8080"
+   *
+   * // Works with template variables in .env too:
+   * // API_URL=https://${API_HOST}:${API_PORT}
+   * const message = Envapter.resolve`Service endpoint: ${'API_URL'}`;
+   * // Returns: "Service endpoint: https://api.example.com:8080"
+   * ```
+   */
+  static resolve(strings, ...keys) {
+    return strings.reduce((result, string, i) => {
+      const envKey = keys[i];
+      const envValue = envKey ? super.get(envKey, "") : "";
+      return result + string + envValue;
+    }, "");
+  }
+  /**
+   * @see {@link Envapter.resolve}
+   */
+  resolve(strings, ...keys) {
+    return _Envapter.resolve(strings, ...keys);
+  }
 };
 
 // src/Envapt.ts
 function createPropertyDecorator(key, fallback, converter, hasFallback) {
   return function(target, prop) {
     const propKey = String(prop);
-    const cacheKey = `${target.constructor.name}.${propKey}`;
+    const className = typeof target === "function" ? target.name : target.constructor.name;
+    const cacheKey = `${className}.${propKey}`;
     Object.defineProperty(target, propKey, {
       get: /* @__PURE__ */ __name(function() {
         let value = EnvaptCache.get(cacheKey);
@@ -853,6 +882,7 @@ var Converters = /* @__PURE__ */ ((Converters2) => {
 
 exports.Converters = Converters;
 exports.Envapt = Envapt;
+exports.EnvaptError = EnvaptError;
 exports.EnvaptErrorCodes = EnvaptErrorCodes;
 exports.Envapter = Envapter;
 exports.Environment = Environment;