@dotenvage/node 0.1.5

package/examples/app-config.ts

@@ -0,0 +1,129 @@
+/**
+ * TypeScript example: Type-safe application configuration
+ *
+ * This shows how to use dotenvage with TypeScript for type-safe
+ * configuration management.
+ */
+
+import * as dotenvage from "../index.js";
+
+// Define your application configuration schema
+interface AppConfig {
+  readonly apiKey: string;
+  readonly databaseUrl: string;
+  readonly port: number;
+  readonly nodeEnv: "development" | "production" | "test";
+  readonly logLevel: "debug" | "info" | "warn" | "error";
+}
+
+// Type-safe config loader
+class ConfigLoader {
+  private loader: dotenvage.JsEnvLoader;
+
+  constructor() {
+    this.loader = dotenvage.JsEnvLoaderNew();
+    this.loader.load(); // Load into process.env
+  }
+
+  /**
+   * Load and validate configuration
+   */
+  loadConfig(): AppConfig {
+    const raw = this.loader.getAllVariables();
+
+    // Validate and transform
+    const apiKey = this.getRequired("API_KEY", raw);
+    const databaseUrl = this.getRequired("DATABASE_URL", raw);
+    const port = this.getNumber("PORT", raw, 8080);
+    const nodeEnv = this.getEnum(
+      "NODE_ENV",
+      raw,
+      ["development", "production", "test"],
+      "development"
+    ) as AppConfig["nodeEnv"];
+    const logLevel = this.getEnum(
+      "LOG_LEVEL",
+      raw,
+      ["debug", "info", "warn", "error"],
+      "info"
+    ) as AppConfig["logLevel"];
+
+    return {
+      apiKey,
+      databaseUrl,
+      port,
+      nodeEnv,
+      logLevel,
+    };
+  }
+
+  private getRequired(key: string, env: Record<string, string>): string {
+    const value = env[key] || process.env[key];
+    if (!value) {
+      throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+  }
+
+  private getNumber(
+    key: string,
+    env: Record<string, string>,
+    defaultValue: number
+  ): number {
+    const value = env[key] || process.env[key];
+    if (!value) {
+      return defaultValue;
+    }
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+      console.warn(`Invalid number for ${key}, using default: ${defaultValue}`);
+      return defaultValue;
+    }
+    return parsed;
+  }
+
+  private getEnum<T extends string>(
+    key: string,
+    env: Record<string, string>,
+    validValues: readonly T[],
+    defaultValue: T
+  ): T {
+    const value = (env[key] || process.env[key] || defaultValue).toLowerCase();
+    if (validValues.includes(value as T)) {
+      return value as T;
+    }
+    console.warn(
+      `Invalid value for ${key}: ${value}, using default: ${defaultValue}`
+    );
+    return defaultValue;
+  }
+}
+
+// Usage in your application
+function main() {
+  try {
+    const loader = new ConfigLoader();
+    const config: AppConfig = loader.loadConfig();
+
+    console.log("Application Configuration:");
+    console.log(`  API Key: ${config.apiKey.substring(0, 10)}...`);
+    console.log(`  Database: ${config.databaseUrl}`);
+    console.log(`  Port: ${config.port}`);
+    console.log(`  Environment: ${config.nodeEnv}`);
+    console.log(`  Log Level: ${config.logLevel}`);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`Configuration error: ${error.message}`);
+    } else {
+      console.error("Unknown configuration error");
+    }
+    process.exit(1);
+  }
+}
+
+// Run if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { ConfigLoader, type AppConfig };

package/examples/auto-encrypt.ts

@@ -0,0 +1,132 @@
+/**
+ * TypeScript example: Auto-detection patterns
+ *
+ * Shows how to use pattern matching to determine which
+ * environment variables should be encrypted.
+ */
+
+import * as dotenvage from "../index.js";
+
+// Test various key names
+const testKeys = [
+  "API_KEY",
+  "FLY_API_TOKEN",
+  "SECRET_TOKEN",
+  "DATABASE_PASSWORD",
+  "AWS_SECRET_ACCESS_KEY",
+  "STRIPE_SECRET_KEY",
+  "NODE_ENV",
+  "PORT",
+  "DATABASE_URL",
+  "LOG_LEVEL",
+  "PUBLIC_API_URL",
+] as const;
+
+// Type-safe function to check if a key should be encrypted
+function shouldEncryptKey(key: string): boolean {
+  return dotenvage.shouldEncrypt(key);
+}
+
+// Group keys by whether they should be encrypted
+const encryptedKeys: string[] = [];
+const plainKeys: string[] = [];
+
+testKeys.forEach((key) => {
+  if (shouldEncryptKey(key)) {
+    encryptedKeys.push(key);
+  } else {
+    plainKeys.push(key);
+  }
+});
+
+console.log("Auto-detection Results:");
+console.log(`\n🔒 Should encrypt (${encryptedKeys.length}):`);
+encryptedKeys.forEach((key) => {
+  console.log(`  - ${key}`);
+});
+
+console.log(`\n✅ Plain text (${plainKeys.length}):`);
+plainKeys.forEach((key) => {
+  console.log(`  - ${key}`);
+});
+
+// Example: Type-safe helper to encrypt secrets automatically
+class SecretManager {
+  private manager: dotenvage.JsSecretManager;
+
+  constructor() {
+    this.manager = dotenvage.JsSecretManagerNew();
+  }
+
+  /**
+   * Set an environment variable, auto-encrypting if the key matches patterns
+   */
+  setEnvVar(key: string, value: string): string {
+    if (dotenvage.shouldEncrypt(key)) {
+      // Auto-encrypt sensitive keys
+      const encrypted = this.manager.encryptValue(value);
+      console.log(`🔒 Auto-encrypted ${key}`);
+      return encrypted;
+    } else {
+      // Keep plain text for non-sensitive keys
+      console.log(`✅ Kept ${key} as plain text`);
+      return value;
+    }
+  }
+}
+
+// Usage example
+const secretMgr = new SecretManager();
+const apiKey = secretMgr.setEnvVar("API_KEY", "sk_live_abc123");
+const port = secretMgr.setEnvVar("PORT", "8080");
+
+console.log(`\nAPI_KEY (encrypted): ${apiKey.substring(0, 30)}...`);
+console.log(`PORT (plain): ${port}`);
+
+// Type-safe configuration with auto-encryption
+type ConfigEntry<T> = {
+  key: string;
+  value: T;
+  encrypt: boolean;
+};
+
+function createConfig<T>(
+  entries: Array<{ key: string; value: T; encrypt?: boolean }>
+): ConfigEntry<T>[] {
+  const manager = dotenvage.JsSecretManagerGenerate();
+
+  return entries.map((entry) => {
+    const shouldEncrypt =
+      entry.encrypt !== undefined
+        ? entry.encrypt
+        : dotenvage.shouldEncrypt(entry.key);
+
+    let processedValue: T = entry.value;
+
+    if (shouldEncrypt && typeof entry.value === "string") {
+      processedValue = manager.encryptValue(entry.value) as T;
+    }
+
+    return {
+      key: entry.key,
+      value: processedValue,
+      encrypt: shouldEncrypt,
+    };
+  });
+}
+
+const configEntries = createConfig([
+  { key: "API_KEY", value: "sk_live_123" },
+  { key: "PORT", value: "8080" },
+  { key: "DATABASE_URL", value: "postgres://localhost/db" },
+  { key: "SECRET_TOKEN", value: "secret-value" },
+]);
+
+console.log("\nConfig entries:");
+configEntries.forEach((entry) => {
+  const displayValue =
+    entry.encrypt && typeof entry.value === "string"
+      ? `${entry.value.substring(0, 30)}...`
+      : entry.value;
+  console.log(`  ${entry.key}: ${displayValue} ${entry.encrypt ? "🔒" : "✅"}`);
+});

package/examples/basic.js

@@ -0,0 +1,127 @@
+/**
+ * Basic example of using dotenvage in Node.js
+ *
+ * This is the most common pattern: load encrypted .env files into process.env
+ * (similar to how dotenv works with require('dotenv').config())
+ */
+
+const dotenvage = require("../index.js");
+
+// Example 1: Load environment files (MOST COMMON - like dotenv.config())
+// This loads and decrypts .env files, setting variables into process.env
+// Yes, this is how dotenv packages work - they mutate process.env
+console.log(
+  "=== Example 1: Load Environment Files (Most Common) ==="
+);
+try {
+  const loader = dotenvage.JsEnvLoaderNew();
+  loader.load(); // Loads into process.env (mutates environment, like dotenv)
+
+  // Now variables are available in process.env
+  console.log("Loaded variables into process.env");
+  const variableNames = loader.getAllVariableNames();
+  console.log("Total variables:", variableNames.length);
+
+  if (variableNames.length > 0) {
+    console.log(
+      "Sample variables:",
+      variableNames.slice(0, 5).join(", ")
+    );
+    // Example: access a variable (if it exists)
+    const sampleKey = variableNames[0];
+    if (process.env[sampleKey]) {
+      console.log(
+        `Example: process.env.${sampleKey} = ${process.env[
+          sampleKey
+        ].substring(0, 20)}...`
+      );
+    }
+  }
+} catch (error) {
+  console.log(
+    "Note: Environment loading requires a valid encryption key."
+  );
+  console.log(
+    "Set DOTENVAGE_AGE_KEY, AGE_KEY, or EKG_AGE_KEY environment variable."
+  );
+  console.log("Error:", error.message);
+}
+
+// Example 1b: Load without mutating process.env (alternative pattern)
+// Get variables as an object instead of setting process.env
+console.log(
+  "\n=== Example 1b: Get Variables as Object (Non-mutating) ==="
+);
+try {
+  const loader = dotenvage.JsEnvLoaderNew();
+  const variables = loader.getAllVariables(); // Returns object without modifying process.env
+  const keys = Object.keys(variables);
+  console.log(
+    "Got",
+    keys.length,
+    "variables as object (not in process.env)"
+  );
+  if (keys.length > 0) {
+    const sampleKey = keys[0];
+    console.log(
+      `Example: variables.${sampleKey} = ${variables[
+        sampleKey
+      ].substring(0, 20)}...`
+    );
+  }
+} catch (error) {
+  console.log(
+    "Note: Requires valid encryption key. Error:",
+    error.message
+  );
+}
+
+// Example 2: Generate a new encryption key
+console.log("\n=== Example 2: Generate Key ===");
+try {
+  const manager = dotenvage.JsSecretManagerGenerate();
+  const publicKey = manager.publicKeyString();
+  console.log("Generated public key:", publicKey);
+  console.log("Save this key - you'll need it to decrypt values!");
+  console.log(
+    'Set it as: export DOTENVAGE_AGE_KEY="<private-key-string>"'
+  );
+} catch (error) {
+  console.error("Error generating key:", error.message);
+  console.log(
+    'Note: Make sure you have built the native bindings with "npm run build"'
+  );
+}
+
+// Example 3: Encrypt and decrypt a value
+console.log("\n=== Example 3: Encrypt/Decrypt ===");
+try {
+  const manager = dotenvage.JsSecretManagerGenerate();
+  const secret = "my-super-secret-api-key-12345";
+
+  const encrypted = manager.encryptValue(secret);
+  console.log("Original:", secret);
+  console.log("Encrypted:", encrypted);
+
+  const decrypted = manager.decryptValue(encrypted);
+  console.log("Decrypted:", decrypted);
+  console.log("Match:", secret === decrypted ? "✅" : "❌");
+} catch (error) {
+  console.error("Error:", error.message);
+}
+
+// Example 4: Check if key should be encrypted (auto-detection patterns)
+console.log("\n=== Example 4: Auto-detection Patterns ===");
+const keys = [
+  "API_KEY",
+  "FLY_API_TOKEN",
+  "NODE_ENV",
+  "PORT",
+  "DATABASE_URL",
+];
+for (const key of keys) {
+  const shouldEncrypt = dotenvage.shouldEncrypt(key);
+  console.log(
+    `${key}: ${shouldEncrypt ? "🔒 Should encrypt" : "✅ Plain text"}`
+  );
+}

package/examples/encrypt-decrypt.ts

@@ -0,0 +1,56 @@
+/**
+ * TypeScript example: Encryption and decryption
+ */
+
+import * as dotenvage from "../index.js";
+
+// Generate a new key pair
+const manager = dotenvage.JsSecretManagerGenerate();
+
+// Get the public key (can be shared)
+const publicKey: string = manager.publicKeyString();
+console.log(`Public key: ${publicKey}`);
+
+// Encrypt a secret value
+const secret = "sk_live_abc123xyz";
+const encrypted: string = manager.encryptValue(secret);
+console.log(`\nEncrypted: ${encrypted}`);
+
+// Decrypt it back
+const decrypted: string = manager.decryptValue(encrypted);
+console.log(`Decrypted: ${decrypted}`);
+console.log(`Match: ${secret === decrypted ? "✅" : "❌"}`);
+
+// Check if a value is encrypted
+const isEncrypted: boolean = manager.isEncrypted(encrypted);
+console.log(`\nIs encrypted: ${isEncrypted}`);
+
+// Pass through unencrypted values
+const plaintext = "not-encrypted";
+const result: string = manager.decryptValue(plaintext);
+console.log(`Plaintext passthrough: ${result}`);
+
+// Type-safe wrapper function
+function encryptSecret(
+  manager: dotenvage.JsSecretManager,
+  value: string
+): string {
+  return manager.encryptValue(value);
+}
+
+function decryptSecret(
+  manager: dotenvage.JsSecretManager,
+  value: string
+): string {
+  return manager.decryptValue(value);
+}
+
+// Usage with type safety
+const apiToken = "my-api-token-123";
+const encryptedToken = encryptSecret(manager, apiToken);
+const decryptedToken = decryptSecret(manager, encryptedToken);
+
+console.log(`\nType-safe encryption:`);
+console.log(`Original: ${apiToken}`);
+console.log(`Encrypted: ${encryptedToken.substring(0, 30)}...`);
+console.log(`Decrypted: ${decryptedToken}`);

package/examples/load-env.ts

@@ -0,0 +1,51 @@
+/**
+ * TypeScript example: Loading environment variables
+ *
+ * This is the most common pattern - loading encrypted .env files
+ * into process.env (like dotenv.config())
+ */
+
+import * as dotenvage from "../index.js";
+
+// Pattern 1: Load into process.env (most common, mutates environment)
+// This matches how dotenv works - variables become available in process.env
+const loader = dotenvage.JsEnvLoaderNew();
+loader.load(); // Sets variables in process.env
+
+// Now access via process.env
+const apiKey = process.env.API_KEY;
+const databaseUrl = process.env.DATABASE_URL;
+
+console.log("Loaded variables into process.env");
+console.log(`API_KEY exists: ${!!apiKey}`);
+console.log(`DATABASE_URL exists: ${!!databaseUrl}`);
+
+// Pattern 2: Get as object (non-mutating, functional style)
+// Use this when you don't want to modify process.env
+const loader2 = dotenvage.JsEnvLoaderNew();
+const env = loader2.getAllVariables(); // Returns Record<string, string>
+
+// Type-safe access
+type EnvConfig = {
+  API_KEY?: string;
+  DATABASE_URL?: string;
+  PORT?: string;
+};
+
+const config: EnvConfig = env as EnvConfig;
+console.log("\nGot variables as object:");
+console.log(`API_KEY: ${config.API_KEY ? "✅" : "❌"}`);
+console.log(`DATABASE_URL: ${config.DATABASE_URL ? "✅" : "❌"}`);
+console.log(`PORT: ${config.PORT || "default (8080)"}`);
+
+// Pattern 3: Load from specific directory
+const loader3 = dotenvage.JsEnvLoaderNew();
+loader3.loadFromDir("./config"); // Load .env files from ./config directory
+
+// Pattern 4: Get variable names only (without loading into environment)
+const loader4 = dotenvage.JsEnvLoaderNew();
+const variableNames: string[] = loader4.getAllVariableNames();
+console.log(`\nFound ${variableNames.length} variables in .env files:`);
+variableNames.slice(0, 5).forEach((name) => {
+  console.log(`  - ${name}`);
+});

package/examples/nextjs-config.ts

@@ -0,0 +1,132 @@
+/**
+ * TypeScript example: Next.js integration
+ *
+ * Shows how to integrate dotenvage with Next.js for
+ * server-side configuration.
+ */
+
+import * as dotenvage from "../index.js";
+
+// Load environment variables (do this early in your app)
+// In Next.js, you'd typically do this in next.config.js or in your API routes
+const loader = dotenvage.JsEnvLoaderNew();
+loader.load();
+
+// Type-safe Next.js environment configuration
+interface NextjsEnv {
+  readonly NEXT_PUBLIC_APP_URL: string;
+  readonly DATABASE_URL: string;
+  readonly API_KEY: string;
+  readonly NEXT_PUBLIC_API_URL?: string;
+  readonly NODE_ENV: "development" | "production" | "test";
+}
+
+// Get environment variables with type safety
+function getNextjsEnv(): NextjsEnv {
+  const required = (key: keyof NextjsEnv): string => {
+    const value = process.env[key];
+    if (!value) {
+      throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return value;
+  };
+
+  const optional = (key: string): string | undefined => {
+    return process.env[key];
+  };
+
+  return {
+    NEXT_PUBLIC_APP_URL: required("NEXT_PUBLIC_APP_URL"),
+    DATABASE_URL: required("DATABASE_URL"),
+    API_KEY: required("API_KEY"),
+    NEXT_PUBLIC_API_URL: optional("NEXT_PUBLIC_API_URL"),
+    NODE_ENV: (process.env.NODE_ENV || "development") as NextjsEnv["NODE_ENV"],
+  };
+}
+
+// Example: Next.js API route handler
+export function createApiHandler<T extends Record<string, unknown>>(
+  handler: (env: NextjsEnv, req: T) => Promise<Response>
+) {
+  return async (req: T): Promise<Response> => {
+    try {
+      const env = getNextjsEnv();
+      return await handler(env, req);
+    } catch (error) {
+      console.error("API error:", error);
+      return new Response(
+        JSON.stringify({ error: "Internal server error" }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+  };
+}
+
+// Example: Next.js API route
+async function exampleApiRoute(
+  env: NextjsEnv,
+  req: { method: string }
+): Promise<Response> {
+  if (req.method !== "GET") {
+    return new Response("Method not allowed", { status: 405 });
+  }
+
+  return new Response(
+    JSON.stringify({
+      message: "API is working",
+      environment: env.NODE_ENV,
+      // Don't expose secrets in API responses!
+      hasApiKey: !!env.API_KEY,
+    }),
+    {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }
+  );
+}
+
+// Export the handler (Next.js pattern)
+export const handler = createApiHandler(exampleApiRoute);
+
+// Example: Server-side component data fetching
+export async function getServerSideData() {
+  const env = getNextjsEnv();
+
+  // Use the decrypted environment variables
+  const response = await fetch(`${env.NEXT_PUBLIC_API_URL}/api/data`, {
+    headers: {
+      Authorization: `Bearer ${env.API_KEY}`,
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to fetch data");
+  }
+
+  return response.json();
+}
+
+// Example: Environment validation at startup
+export function validateNextjsEnv(): void {
+  try {
+    const env = getNextjsEnv();
+    console.log("✅ All required environment variables are set");
+    console.log(`   Environment: ${env.NODE_ENV}`);
+    console.log(`   App URL: ${env.NEXT_PUBLIC_APP_URL}`);
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`❌ Environment validation failed: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+// Run validation if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  validateNextjsEnv();
+}
+
+export { getNextjsEnv, type NextjsEnv };

package/examples/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "types": ["node"],
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["*.ts", "**/*.ts"],
+  "exclude": ["node_modules"]
+}