@ojolowoblue/lamba 1.0.4 → 1.0.6

package/README.md

@@ -27,7 +27,7 @@ Deployed via CDN or installed via NPM, `lamba` injects a non-intrusive floating
 Include the script tag in your `index.html` file before your application bundle:
 
 ```html
-<script src="https://unpkg.com/@ojolowoblue/lamba"></script>
+<script src="https://unpkg.com/@ojolowoblue/lamba" data-lamba-auto></script>
 ```
 
 That's it! A floating settings button (⚙️) will automatically appear in the bottom-right corner of your web page.
@@ -52,11 +52,11 @@ import lamba from '@ojolowoblue/lamba';
 lamba.init({
   position: 'bottom-right',
   env: {
-    // Supports any env prefix (VITE_, NEXT_PUBLIC_, REACT_APP_, VUE_APP_, PUBLIC_) or custom keys:
+    // Supports any data type (strings, numbers, booleans, objects) & any prefix:
     NEXT_PUBLIC_API_URL: 'https://api.dev.example.com',
-    REACT_APP_FEATURE_FLAG: 'false',
-    VITE_ENABLE_ANALYTICS: 'true',
-    API_BASE_URL: 'https://api.dev.example.com',
+    PORT: 3000,
+    VITE_ENABLE_ANALYTICS: true,
+    FEATURE_FLAGS: { newCheckout: true },
   },
 });
 ```
@@ -88,7 +88,7 @@ Wrap your existing `import.meta.env` (Vite) or `process.env` (Webpack/Next.js) o
 // src/config.ts
 import lamba from '@ojolowoblue/lamba';
 
-// Wrap your env object in a dynamic ES Proxy
+// Wrap your env object in a dynamic ES Proxy (preserves primitive boolean & number types!)
 export const env = lamba.wrap(import.meta.env);
 
 // Access keys anywhere in your application:
@@ -121,15 +121,15 @@ import React from 'react';
 import { useLambaEnv } from '@ojolowoblue/lamba/react';
 
 export function UserDashboard() {
-  const apiBase = useLambaEnv('VITE_API_BASE_URL', 'https://api.dev.com');
-  const showBetaFeature = useLambaEnv('VITE_FEATURE_BETA_UI', 'false');
+  const apiBase = useLambaEnv<string>('VITE_API_BASE_URL', 'https://api.dev.com');
+  const isBetaEnabled = useLambaEnv<boolean>('VITE_FEATURE_BETA_UI', false);
 
   return (
     <div style={{ padding: '24px' }}>
       <h1>Dashboard</h1>
       <p>Connected Environment: <code>{apiBase}</code></p>
       
-      {showBetaFeature === 'true' && (
+      {isBetaEnabled && (
         <div className="beta-banner">
           🚀 Beta UI Enabled Live via lamba!
         </div>
@@ -147,14 +147,14 @@ Import `useLambaEnv` from `lamba/vue` as a reactive composition Vue Ref:
 <script setup lang="ts">
 import { useLambaEnv } from '@ojolowoblue/lamba/vue';
 
-const apiBase = useLambaEnv('VITE_API_BASE_URL', 'https://api.dev.com');
-const featureFlag = useLambaEnv('VITE_NEW_HEADER', 'false');
+const apiBase = useLambaEnv<string>('VITE_API_BASE_URL', 'https://api.dev.com');
+const isNewHeader = useLambaEnv<boolean>('VITE_NEW_HEADER', false);
 </script>
 
 <template>
   <div class="container">
     <h2>Current Backend: {{ apiBase }}</h2>
-    <header v-if="featureFlag === 'true'">
+    <header v-if="isNewHeader">
       <h3>✨ New Header Component</h3>
     </header>
   </div>
@@ -167,27 +167,29 @@ const featureFlag = useLambaEnv('VITE_NEW_HEADER', 'false');
 
 ### `lamba.init(options?: LambaOptions): LambaManager`
 
-Initializes the lamba manager, hydrates saved overrides from `localStorage`, enables network interceptors, and mounts the floating Shadow DOM UI.
+Initializes the lamba manager, hydrates saved overrides from the configured storage backend, enables network interceptors, and mounts the floating Shadow DOM UI.
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `env` | `Record<string, string>` | `{}` | Initial default key-value pairs of environment variables. |
+| `env` | `Record<string, any>` | `{}` | Initial default key-value pairs of environment variables (supports strings, numbers, booleans, objects). |
 | `enabled` | `boolean` | `true` | Set to `false` to disable lamba (e.g. in production builds). |
 | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Screen position for the floating widget launcher button. |
 | `secretKeysPattern` | `RegExp` | `/(KEY\|SECRET\|TOKEN\|PASSWORD\|AUTH\|PRIVATE)/i` | Regular expression to automatically obscure sensitive keys in the UI. |
 | `autoFetchEnvFile` | `boolean` | `false` | Whether to attempt fetching root `/.env` file during local development. |
 | `interceptNetworkRequests` | `boolean` | `true` | Whether to implicitly intercept `fetch` & `XHR` calls matching original base URLs. |
 | `allowedPrefixes` | `string \| string[] \| RegExp \| null` | `null` | Optional prefix filter (e.g. `['VITE_', 'NEXT_PUBLIC_']`). Omitting allows ALL keys regardless of prefix. |
+| `storageStrategy` | `'local' \| 'session' \| 'memory'` | `'local'` | Where overrides and presets are persisted. See [Storage Strategies](#-storage-strategies) below. |
+| `storage` | `LambaStorageAdapter` | `undefined` | Provide a fully custom storage adapter. Takes precedence over `storageStrategy`. |
 
 ---
 
 ### Core Methods
 
-#### `lamba.get(key: string, fallback?: string): string`
-Returns the active value for the specified environment key (returns active override if present, otherwise default value or fallback).
+#### `lamba.get<T = any>(key: string, fallback?: T): T`
+Returns the active value for the specified environment key (returns active override if present, otherwise default value or fallback). Preserves numbers, booleans, and objects.
 
-#### `lamba.set(key: string, value: string): void`
-Programmatically overrides an environment variable live at runtime. The change is persisted in `localStorage` and triggers UI and listener updates.
+#### `lamba.set(key: string, value: any): void`
+Programmatically overrides an environment variable live at runtime with any data type. The change is persisted in the configured storage backend and triggers UI and listener updates.
 
 #### `lamba.remove(key: string): void`
 Removes an override for a specific environment variable key, reverting it to its default value.
@@ -212,6 +214,57 @@ Programmatically controls the visibility of the lamba modal panel.
 
 ---
 
+## 🔐 Storage Strategies
+
+Control where lamba persists overrides and presets via the `storageStrategy` option:
+
+| Strategy | Visibility in DevTools | Survives Tab Close? | XSS Storage Scraping Risk |
+| :--- | :--- | :--- | :--- |
+| `'local'` *(default)* | ⚠️ Visible (plain-text) | ✅ Yes (Indefinitely) | ⚠️ Yes |
+| `'session'` | ⚠️ Visible (plain-text) | ❌ No (Cleared on close) | ⚠️ Yes |
+| `'memory'` | ✅ **Not visible (0 bytes stored)** | ❌ No (GC'd on close) | ✅ **No** |
+
+### In-Memory (Most Secure)
+
+```typescript
+lamba.init({
+  storageStrategy: 'memory', // Nothing written to DevTools Storage
+  env: { VITE_API_URL: import.meta.env.VITE_API_URL },
+});
+```
+
+### Session (Tab-Ephemeral)
+
+```typescript
+lamba.init({
+  storageStrategy: 'session', // Cleared automatically when tab closes
+  env: { VITE_API_URL: import.meta.env.VITE_API_URL },
+});
+```
+
+### Custom Adapter
+
+Implement the `LambaStorageAdapter` interface to plug in any storage backend (encrypted storage, Electron keytar, IndexedDB, etc.):
+
+```typescript
+import lamba, { type LambaStorageAdapter } from '@ojolowoblue/lamba';
+
+// Example: an encrypted wrapper around sessionStorage
+const encryptedAdapter: LambaStorageAdapter = {
+  getItem: (key) => decrypt(sessionStorage.getItem(key)),
+  setItem: (key, value) => sessionStorage.setItem(key, encrypt(value)),
+  removeItem: (key) => sessionStorage.removeItem(key),
+  clear: () => sessionStorage.clear(),
+};
+
+lamba.init({
+  storage: encryptedAdapter,
+  env: { VITE_API_URL: import.meta.env.VITE_API_URL },
+});
+```
+
+---
+
 ## 🔒 Production Security Best Practice
 
 To prevent end-users from overriding environment variables in production, conditionally initialize `lamba` only in non-production environments:
@@ -221,6 +274,7 @@ import lamba from '@ojolowoblue/lamba';
 
 lamba.init({
   enabled: process.env.NODE_ENV !== 'production',
+  storageStrategy: 'memory', // Use memory storage so nothing lingers in DevTools
   env: {
     VITE_API_URL: import.meta.env.VITE_API_URL,
   },
@@ -233,12 +287,12 @@ lamba.init({
 
 <details>
 <summary><b>Does lamba modify my local <code>.env</code> files on disk?</b></summary>
-<p>No. <code>lamba</code> operates entirely in browser memory and persists overrides in <code>localStorage</code>. It does not write to disk, so your git status remains clean.</p>
+<p>No. <code>lamba</code> operates entirely in browser memory and optionally persists overrides in storage. It does not write to disk, so your git status remains clean.</p>
 </details>
 
 <details>
 <summary><b>Do overrides persist when I refresh the page?</b></summary>
-<p>Yes. Overrides and active preset profiles are saved in <code>localStorage</code> and automatically restored upon page reloads.</p>
+<p>It depends on the <code>storageStrategy</code>. With <code>'local'</code> (default), overrides persist indefinitely. With <code>'session'</code>, they survive reloads but clear when the tab is closed. With <code>'memory'</code>, overrides are lost on any page reload.</p>
 </details>
 
 <details>

package/dist/index.d.mts

@@ -1,21 +1,68 @@
+/**
+ * Abstract interface for pluggable storage backends used by lamba to persist
+ * overrides and presets. All methods are synchronous for simplicity (async
+ * adapters can wrap with Promises if needed in custom implementations).
+ */
+interface LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * LocalStorage-backed adapter (default).
+ * Overrides persist indefinitely across tabs and page reloads.
+ * Visible in DevTools → Application → Local Storage.
+ */
+declare class LocalStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * SessionStorage-backed adapter.
+ * Overrides survive page reloads within the same tab, but are automatically
+ * destroyed when the tab is closed. Still visible in DevTools Storage panel.
+ */
+declare class SessionStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * In-memory adapter.
+ * The most secure option: zero bytes written to any browser storage mechanism.
+ * Overrides exist only in JavaScript heap memory and are destroyed when the
+ * tab/page is closed or navigated away. Nothing appears in DevTools Storage.
+ */
+declare class MemoryStorageAdapter implements LambaStorageAdapter {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+
 interface EnvVariable {
     key: string;
-    value: string;
-    defaultValue: string;
+    value: any;
+    defaultValue: any;
     isOverridden: boolean;
     isSecret?: boolean;
 }
 interface PresetProfile {
     id: string;
     name: string;
-    overrides: Record<string, string>;
+    overrides: Record<string, any>;
     createdAt: number;
 }
 interface LambaOptions {
     /**
-     * Initial environment variable key-values to supply to lamba.
+     * Initial environment variable key-values to supply to lamba. Accepts strings, numbers, booleans, objects, etc.
      */
-    env?: Record<string, string>;
+    env?: Record<string, any>;
     /**
      * Whether lamba floating UI is enabled. Defaults to true in non-production or when specified.
      */
@@ -46,8 +93,24 @@ interface LambaOptions {
      * If omitted, null, or empty, ALL environment variable keys are allowed and supported regardless of prefix.
      */
     allowedPrefixes?: string | string[] | RegExp | null;
+    /**
+     * Storage strategy for persisting overrides and presets across page reloads:
+     * - `'local'`   — (default) Standard `localStorage`. Persists indefinitely across tabs & reloads.
+     *               Visible in DevTools → Application → Local Storage.
+     * - `'session'` — `sessionStorage`. Survives page reloads within the same tab, but cleared
+     *               when the tab is closed. Visible in DevTools → Application → Session Storage.
+     * - `'memory'`  — In-memory only. Most secure option — zero bytes written to any browser storage.
+     *               Overrides are destroyed when the tab closes or navigates away.
+     *               Nothing appears in DevTools Storage.
+     */
+    storageStrategy?: 'local' | 'session' | 'memory';
+    /**
+     * Provide a fully custom storage adapter that conforms to the `LambaStorageAdapter` interface.
+     * When provided, this takes precedence over `storageStrategy`.
+     */
+    storage?: LambaStorageAdapter;
 }
-type EnvChangeListener = (key: string, value: string, isOverridden: boolean) => void;
+type EnvChangeListener = (key: string, value: any, isOverridden: boolean) => void;
 type StoreChangeListener = (variables: Record<string, EnvVariable>, presets: PresetProfile[], activePresetId: string | null) => void;
 
 /**
@@ -70,7 +133,7 @@ declare class LambaManager {
      * Implicit ES Proxy object where properties like `lamba.env.VITE_API_BASE_URL`
      * return the live active overridden value automatically.
      */
-    env: Record<string, string>;
+    env: Record<string, any>;
     constructor();
     /**
      * Wraps any environment object (such as `import.meta.env` or `process.env`)
@@ -84,11 +147,11 @@ declare class LambaManager {
     /**
      * Gets the active value of an environment variable (returns overridden value if active, otherwise default).
      */
-    get(key: string, fallback?: string): string;
+    get<T = any>(key: string, fallback?: T): T;
     /**
      * Overrides an environment variable live at runtime.
      */
-    set(key: string, value: string): void;
+    set(key: string, value: any): void;
     /**
      * Removes an override for a specific environment variable key.
      */
@@ -116,4 +179,4 @@ declare class LambaManager {
 }
 declare const lamba: LambaManager;
 
-export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type PresetProfile, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };
+export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type LambaStorageAdapter, LocalStorageAdapter, MemoryStorageAdapter, type PresetProfile, SessionStorageAdapter, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };

package/dist/index.d.ts

@@ -1,21 +1,68 @@
+/**
+ * Abstract interface for pluggable storage backends used by lamba to persist
+ * overrides and presets. All methods are synchronous for simplicity (async
+ * adapters can wrap with Promises if needed in custom implementations).
+ */
+interface LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * LocalStorage-backed adapter (default).
+ * Overrides persist indefinitely across tabs and page reloads.
+ * Visible in DevTools → Application → Local Storage.
+ */
+declare class LocalStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * SessionStorage-backed adapter.
+ * Overrides survive page reloads within the same tab, but are automatically
+ * destroyed when the tab is closed. Still visible in DevTools Storage panel.
+ */
+declare class SessionStorageAdapter implements LambaStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * In-memory adapter.
+ * The most secure option: zero bytes written to any browser storage mechanism.
+ * Overrides exist only in JavaScript heap memory and are destroyed when the
+ * tab/page is closed or navigated away. Nothing appears in DevTools Storage.
+ */
+declare class MemoryStorageAdapter implements LambaStorageAdapter {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+
 interface EnvVariable {
     key: string;
-    value: string;
-    defaultValue: string;
+    value: any;
+    defaultValue: any;
     isOverridden: boolean;
     isSecret?: boolean;
 }
 interface PresetProfile {
     id: string;
     name: string;
-    overrides: Record<string, string>;
+    overrides: Record<string, any>;
     createdAt: number;
 }
 interface LambaOptions {
     /**
-     * Initial environment variable key-values to supply to lamba.
+     * Initial environment variable key-values to supply to lamba. Accepts strings, numbers, booleans, objects, etc.
      */
-    env?: Record<string, string>;
+    env?: Record<string, any>;
     /**
      * Whether lamba floating UI is enabled. Defaults to true in non-production or when specified.
      */
@@ -46,8 +93,24 @@ interface LambaOptions {
      * If omitted, null, or empty, ALL environment variable keys are allowed and supported regardless of prefix.
      */
     allowedPrefixes?: string | string[] | RegExp | null;
+    /**
+     * Storage strategy for persisting overrides and presets across page reloads:
+     * - `'local'`   — (default) Standard `localStorage`. Persists indefinitely across tabs & reloads.
+     *               Visible in DevTools → Application → Local Storage.
+     * - `'session'` — `sessionStorage`. Survives page reloads within the same tab, but cleared
+     *               when the tab is closed. Visible in DevTools → Application → Session Storage.
+     * - `'memory'`  — In-memory only. Most secure option — zero bytes written to any browser storage.
+     *               Overrides are destroyed when the tab closes or navigates away.
+     *               Nothing appears in DevTools Storage.
+     */
+    storageStrategy?: 'local' | 'session' | 'memory';
+    /**
+     * Provide a fully custom storage adapter that conforms to the `LambaStorageAdapter` interface.
+     * When provided, this takes precedence over `storageStrategy`.
+     */
+    storage?: LambaStorageAdapter;
 }
-type EnvChangeListener = (key: string, value: string, isOverridden: boolean) => void;
+type EnvChangeListener = (key: string, value: any, isOverridden: boolean) => void;
 type StoreChangeListener = (variables: Record<string, EnvVariable>, presets: PresetProfile[], activePresetId: string | null) => void;
 
 /**
@@ -70,7 +133,7 @@ declare class LambaManager {
      * Implicit ES Proxy object where properties like `lamba.env.VITE_API_BASE_URL`
      * return the live active overridden value automatically.
      */
-    env: Record<string, string>;
+    env: Record<string, any>;
     constructor();
     /**
      * Wraps any environment object (such as `import.meta.env` or `process.env`)
@@ -84,11 +147,11 @@ declare class LambaManager {
     /**
      * Gets the active value of an environment variable (returns overridden value if active, otherwise default).
      */
-    get(key: string, fallback?: string): string;
+    get<T = any>(key: string, fallback?: T): T;
     /**
      * Overrides an environment variable live at runtime.
      */
-    set(key: string, value: string): void;
+    set(key: string, value: any): void;
     /**
      * Removes an override for a specific environment variable key.
      */
@@ -116,4 +179,4 @@ declare class LambaManager {
 }
 declare const lamba: LambaManager;
 
-export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type PresetProfile, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };
+export { type EnvChangeListener, type EnvVariable, LambaManager, type LambaOptions, type LambaStorageAdapter, LocalStorageAdapter, MemoryStorageAdapter, type PresetProfile, SessionStorageAdapter, type StoreChangeListener, lamba as default, lamba, parseEnvString, stringifyEnv };