vasuzex 2.2.4 → 2.3.1

package/CHANGELOG.md

@@ -1,6 +1,58 @@
 # Changelog
 
 All notable changes to Vasuzex will be documented in this file.
+
+## [2.3.0] - 2026-02-18
+
+### 🚀 Standalone Script Support
+
+This release enables Config and Log facades to work in standalone scripts without Application instance, following Laravel's graceful degradation pattern.
+
+### ✨ Added
+
+#### Config Facade Standalone Mode
+- **Standalone script support** - Config.get() now works without Application instance
+- **Auto-discovery** - Walks up directory tree to find project root with `config/` directory
+- **Config loading** - Loads all .cjs files from `config/` directory using require()
+- **Dot notation** - Full support for nested keys (`database.connections.default.host`)
+- **Caching** - Loaded config cached for performance
+- **Graceful fallback** - Tries Application-bound service first, falls back if unavailable
+  ```javascript
+  // Now works in standalone scripts!
+  import { Config } from 'vasuzex';
+  const dbHost = Config.get('database.connections.default.host', 'localhost');
+  ```
+
+#### Log Facade Standalone Mode
+- **Standalone script support** - Log methods now work without Application instance
+- **Console fallback** - Falls back to console.log with structured formatting
+- **ISO timestamps** - Production-quality log output: `[2026-02-18T05:21:16.107Z] [INFO] message`
+- **Respects LOG_LEVEL** - Debug logs only show if `LOG_LEVEL=debug` or `DEBUG=true`
+- **All log levels** - debug(), info(), warn(), error() all supported
+- **Graceful fallback** - Tries Application-bound logger first, falls back if unavailable
+  ```javascript
+  // Now works in standalone scripts!
+  import { Log } from 'vasuzex';
+  Log.info('Processing data', { records: 100 });
+  // Output: [2026-02-18T05:21:16.107Z] [INFO] Processing data {"records":100}
+  ```
+
+### 🔧 Technical Details
+
+- **Service container priority** - Always tries Application instance first (backward compatible)
+- **Zero breaking changes** - All existing apps continue working unchanged
+- **Laravel pattern** - Follows Laravel's facade graceful degradation pattern
+- **Production-ready** - Proper error handling, silent failures, performance optimized
+
+### 🎯 Use Cases
+
+This enables:
+- ✅ Database migration scripts using Config.get()
+- ✅ Cron jobs and workers using Log.info()
+- ✅ CLI tools without full Application bootstrap
+- ✅ Test scripts accessing configuration
+- ✅ Utility scripts with proper logging
+
 ## [2.2.0] - 2026-02-06
 
 ### 🚀 Major Pro-Level Enhancements

package/VASUZEX-V2.3.0-RELEASE.md

@@ -0,0 +1,189 @@
+# vasuzex v2.3.0 Release Notes
+
+## Laravel-Style Standalone Script Support
+
+### Overview
+Added standalone script support to Config and Log facades, following Laravel's best practices for graceful facade degradation. This enables vasuzex facades to work in **both** application contexts (with service container) and standalone scripts (without Application instance).
+
+### Why This is v2.3.0 (MINOR), Not a Patch
+This is a **new feature** that maintains backward compatibility:
+- ✅ Existing apps continue to work exactly as before (no breaking changes)
+- ✅ Adds new capability: facades now work in standalone scripts
+- ✅ Follows Laravel patterns (service container first, graceful fallback)
+- ✅ Production-ready implementation with proper error handling
+
+Per semver: `MAJOR.MINOR.PATCH` - this is a MINOR version (new backward-compatible functionality).
+
+---
+
+## Changes Required
+
+### 1. `/framework/Support/Facades/Config.js`
+
+**Purpose**: Enable Config.get() in standalone scripts by loading .cjs config files from `config/` directory.
+
+**Implementation**:
+- Tries Application-bound config service first (normal app behavior)
+- Falls back to direct config file loading if no Application
+- Discovers project root by walking up directory tree
+- Loads all .cjs files from `config/` directory using `require()`
+- Supports dot notation (`database.connections.default.host`)
+- Caches loaded config for performance
+
+**File location**: `framework/Support/Facades/Config.js`
+
+**Full file content**: See `/Users/rishi/Desktop/work/neasto/node_modules/.pnpm/vasuzex@2.2.4_@azure+core-client@1.10.1_@types+node@25.2.3_react-redux@9.2.0_@types+rea_6b288229c8b08a609ae395ef19989414/node_modules/vasuzex/framework/Support/Facades/Config.js`
+
+---
+
+### 2. `/framework/Support/Facades/Log.js`
+
+**Purpose**: Enable Log.info/error/warn/debug in standalone scripts with console fallback.
+
+**Implementation**:
+- Tries Application-bound logger first (normal app behavior)
+- Falls back to console.log with structured formatting
+- ISO timestamps for production-quality logs
+- Respects LOG_LEVEL environment variable (debug only shows if LOG_LEVEL=debug)
+- All log levels supported: debug, info, warn, error
+
+**File location**: `framework/Support/Facades/Log.js`
+
+**Full file content**: See `/Users/rishi/Desktop/work/neasto/node_modules/.pnpm/vasuzex@2.2.4_@azure+core-client@1.10.1_@types+node@25.2.3_react-redux@9.2.0_@types+rea_6b288229c8b08a609ae395ef19989414/node_modules/vasuzex/framework/Support/Facades/Log.js`
+
+---
+
+## Testing Done
+
+### Standalone Script Tests ✅
+1. ✅ Config.get() - basic values (app.name, app.env)
+2. ✅ Config.get() - nested dot notation (database.connections.default.host)
+3. ✅ Config.get() - default values for missing keys
+4. ✅ Log.info() - with structured data
+5. ✅ Log.error() - with error data
+6. ✅ Log.warn() - with warning data
+7. ✅ Log.debug() - respects LOG_LEVEL
+
+### Real-World Script Tests ✅
+1. ✅ Elasticsearch setup scripts (setup-indices.js)
+2. ✅ Elasticsearch client connection (ElasticsearchClient.js)
+3. ✅ Dispatch test scripts (full-dispatch-test.cjs)
+4. ✅ Database bootstrap scripts (work without Application)
+
+### Backward Compatibility ✅
+- Apps with Application instance continue using service container
+- No changes required to existing application code
+- Facades try App context first, fall back only if needed
+
+---
+
+## Laravel Pattern Compliance
+
+### Config Facade Pattern:
+- ✓ Loads from `config/` directory (like Laravel's config path)
+- ✓ Supports dot notation (like Laravel's `config('database.default')`)
+- ✓ Returns default if key not found
+- ✓ Caches loaded config (like Laravel's config cache)
+
+### Log Facade Pattern:
+- ✓ Service container first (facade root)
+- ✓ Graceful degradation to console
+- ✓ Standard log levels (debug/info/warn/error)
+- ✓ Respects environment settings
+
+### Facade Pattern:
+- ✓ Service container priority (tries Application first)
+- ✓ Graceful fallback (standalone mode)
+- ✓ No breaking changes (backward compatible)
+- ✓ Production-ready error handling
+
+---
+
+## Publishing Instructions
+
+### 1. Copy Changes to vasuzex Repo
+Copy updated files from neasto's node_modules:
+```bash
+# Config.js
+cp /Users/rishi/Desktop/work/neasto/node_modules/.pnpm/vasuzex@2.2.4_*/node_modules/vasuzex/framework/Support/Facades/Config.js \
+   <vasuzex-repo>/framework/Support/Facades/Config.js
+
+# Log.js
+cp /Users/rishi/Desktop/work/neasto/node_modules/.pnpm/vasuzex@2.2.4_*/node_modules/vasuzex/framework/Support/Facades/Log.js \
+   <vasuzex-repo>/framework/Support/Facades/Log.js
+```
+
+### 2. Update package.json
+```json
+{
+  "version": "2.3.0"
+}
+```
+
+### 3. Update CHANGELOG.md
+```markdown
+## [2.3.0] - 2026-02-18
+
+### Added
+- **Standalone Script Support**: Config and Log facades now work without Application instance
+- Config facade loads .cjs files from config/ directory in standalone mode
+- Log facade falls back to console.log with ISO timestamps in standalone mode
+- Graceful degradation pattern: tries service container first, falls back if no Application
+
+### Changed
+- Config.js: Enhanced with standalone config loading (backward compatible)
+- Log.js: Enhanced with console fallback logging (backward compatible)
+
+### Technical
+- Follows Laravel service container pattern with graceful fallback
+- Production-ready error handling
+- Zero breaking changes - all existing apps continue working unchanged
+```
+
+### 4. Git Workflow
+```bash
+git checkout -b feature/standalone-facade-support
+git add framework/Support/Facades/Config.js
+git add framework/Support/Facades/Log.js
+git add package.json
+git add CHANGELOG.md
+git commit -m "feat: Add standalone script support to Config and Log facades (v2.3.0)
+
+- Enable facades to work without Application instance
+- Load config from files in standalone mode
+- Fallback logging for standalone scripts
+- Maintains backward compatibility
+- Follows Laravel graceful degradation pattern"
+git push origin feature/standalone-facade-support
+```
+
+### 5. Create PR & Merge
+Review changes, merge to main
+
+### 6. Publish to npm
+```bash
+npm version 2.3.0
+npm publish
+git push --tags
+```
+
+### 7. Update neasto
+```bash
+cd /Users/rishi/Desktop/work/neasto
+pnpm update vasuzex
+# Should install vasuzex@2.3.0
+```
+
+---
+
+## Summary
+
+This is a **proper Laravel-standard implementation**, not a quick patch:
+
+✅ **Service container priority** - Uses Application-bound services when available  
+✅ **Graceful degradation** - Falls back intelligently when no Application  
+✅ **Production-ready** - Proper error handling, caching, performance  
+✅ **Zero breaking changes** - All existing code continues working  
+✅ **Laravel patterns** - Follows Laravel's facade and config patterns  
+
+**Version: 2.3.0** (minor version - new backward-compatible feature)

package/framework/Support/Facades/Config.js

@@ -1,13 +1,147 @@
 /**
  * Config Facade
+ * Enhanced to support standalone scripts without Application instance
  */
 
 import { Facade, createFacade } from './Facade.js';
+import path from 'path';
+import { existsSync, readdirSync } from 'fs';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+// Create require for loading .cjs files
+const require = createRequire(import.meta.url);
+
+let standaloneConfig = null;
+let standaloneConfigLoaded = false;
 
 class ConfigFacade extends Facade {
   static getFacadeAccessor() {
     return 'config';
   }
+
+  /**
+   * Get config value with standalone fallback
+   * Works in both app context and standalone scripts
+   */
+  static get(key, defaultValue = null) {
+    // Try app context first (if Application exists)
+    if (this.app) {
+      try {
+        const instance = this.getFacadeRoot();
+        return instance.get(key, defaultValue);
+      } catch (error) {
+        // Fall through to standalone mode
+      }
+    }
+
+    // Standalone mode: Load config directly
+    return this.getStandalone(key, defaultValue);
+  }
+
+  /**
+   * Load config in standalone mode (no Application)
+   * Discovers project root and loads config files
+   */
+  static getStandalone(key, defaultValue = null) {
+    if (!standaloneConfigLoaded) {
+      this.loadStandaloneConfig();
+    }
+
+    if (!standaloneConfig) {
+      return defaultValue;
+    }
+
+    // Navigate nested keys (e.g., 'database.connections.default')
+    const keys = key.split('.');
+    let value = standaloneConfig;
+
+    for (const k of keys) {
+      if (value && typeof value === 'object' && k in value) {
+        value = value[k];
+      } else {
+        return defaultValue;
+      }
+    }
+
+    return value !== undefined ? value : defaultValue;
+  }
+
+  /**
+   * Load all config files from config/ directory
+   */
+  static loadStandaloneConfig() {
+    try {
+      // Find project root (look for config/ directory)
+      const rootDir = this.findProjectRoot();
+      if (!rootDir) {
+        standaloneConfig = {};
+        standaloneConfigLoaded = true;
+        return;
+      }
+
+      const configDir = path.join(rootDir, 'config');
+      if (!existsSync(configDir)) {
+        standaloneConfig = {};
+        standaloneConfigLoaded = true;
+        return;
+      }
+
+      // Load all .cjs config files
+      const files = readdirSync(configDir);
+      standaloneConfig = {};
+
+      for (const file of files) {
+        if (file.endsWith('.cjs')) {
+          const configName = file.replace(/\.cjs$/, '');
+          const configPath = path.join(configDir, file);
+          
+          try {
+            // Clear require cache to get fresh config
+            const resolvedPath = require.resolve(configPath);
+            delete require.cache[resolvedPath];
+            
+            // Load config file
+            const configData = require(configPath);
+            standaloneConfig[configName] = configData;
+          } catch (error) {
+            // Silently skip files that can't be loaded
+          }
+        }
+      }
+
+      standaloneConfigLoaded = true;
+    } catch (error) {
+      standaloneConfig = {};
+      standaloneConfigLoaded = true;
+    }
+  }
+
+  /**
+   * Find project root by looking for config/ directory
+   */
+  static findProjectRoot() {
+    try {
+      // Start from current working directory
+      let dir = process.cwd();
+      
+      // Walk up until we find config/
+      for (let i = 0; i < 10; i++) {
+        const configPath = path.join(dir, 'config');
+        if (existsSync(configPath)) {
+          return dir;
+        }
+        
+        const parent = path.dirname(dir);
+        if (parent === dir) break; // Reached filesystem root
+        dir = parent;
+      }
+
+      return null;
+    } catch (error) {
+      return null;
+    }
+  }
 }
 
 export default createFacade(ConfigFacade);

package/framework/Support/Facades/Log.js

@@ -1,5 +1,6 @@
 /**
  * Log Facade
+ * Enhanced to support standalone scripts without Application instance
  */
 
 import { Facade, createFacade } from './Facade.js';
@@ -8,6 +9,66 @@ class LogFacade extends Facade {
   static getFacadeAccessor() {
     return 'log';
   }
+
+  /**
+   * Fallback logging methods for standalone scripts
+   */
+  static log(level, message, data = null) {
+    const timestamp = new Date().toISOString();
+    const dataStr = data ? ' ' + JSON.stringify(data) : '';
+    console.log(`[${timestamp}] [${level.toUpperCase()}] ${message}${dataStr}`);
+  }
+
+  static debug(message, data = null) {
+    if (this.app) {
+      try {
+        const instance = this.getFacadeRoot();
+        return instance.debug(message, data);
+      } catch (error) {
+        // Fall through to standalone mode
+      }
+    }
+    // Standalone: Only log debug in verbose mode
+    if (process.env.LOG_LEVEL === 'debug' || process.env.DEBUG) {
+      this.log('debug', message, data);
+    }
+  }
+
+  static info(message, data = null) {
+    if (this.app) {
+      try {
+        const instance = this.getFacadeRoot();
+        return instance.info(message, data);
+      } catch (error) {
+        // Fall through to standalone mode
+      }
+    }
+    this.log('info', message, data);
+  }
+
+  static warn(message, data = null) {
+    if (this.app) {
+      try {
+        const instance = this.getFacadeRoot();
+        return instance.warn(message, data);
+      } catch (error) {
+        // Fall through to standalone mode
+      }
+    }
+    this.log('warn', message, data);
+  }
+
+  static error(message, data = null) {
+    if (this.app) {
+      try {
+        const instance = this.getFacadeRoot();
+        return instance.error(message, data);
+      } catch (error) {
+        // Fall through to standalone mode
+      }
+    }
+    this.log('error', message, data);
+  }
 }
 
 export default createFacade(LogFacade);

package/frontend/react-ui/components/DataTable/DataTable.jsx

@@ -10,6 +10,7 @@
  * - Rows per page selector
  * - Action buttons (edit/view/delete/switch)
  * - Loading and empty states
+ * - State persistence (restores page/filters when navigating back)
  * 
  * @module components/DataTable
  */
@@ -38,6 +39,8 @@ import { Pagination } from "./Pagination.jsx";
  * @param {string} props.initialStatusFilter - Initial status filter (all/true/false)
  * @param {number} props.initialLimit - Initial rows per page
  * @param {string} props.emptyText - Text to show when no data
+ * @param {boolean} props.persistState - Enable state persistence (default: true)
+ * @param {string} props.stateKey - Custom key for state storage (default: derived from apiUrl)
  */
 export function DataTable(props) {
   // Internal refresh key for self-refresh
@@ -60,6 +63,8 @@ export function DataTable(props) {
     onDelete,
     onToggle,
     api, // API client instance passed as prop
+    persistState = true, // Enable state persistence by default
+    stateKey, // Optional custom state key
   } = props;
 
   // Validate that api client is provided
@@ -67,6 +72,66 @@ export function DataTable(props) {
     throw new Error('DataTable requires "api" prop - pass your API client instance');
   }
 
+  // Generate unique storage key based on apiUrl or custom stateKey
+  const storageKey = React.useMemo(() => {
+    if (stateKey) return `datatable_${stateKey}`;
+    // Use apiUrl as key (remove query params for consistency)
+    const cleanUrl = apiUrl.split('?')[0];
+    return `datatable_${cleanUrl.replace(/[^a-zA-Z0-9]/g, '_')}`;
+  }, [apiUrl, stateKey]);
+
+  // Helper to load persisted state
+  const loadPersistedState = React.useCallback(() => {
+    if (!persistState) return null;
+    try {
+      const stored = sessionStorage.getItem(storageKey);
+      return stored ? JSON.parse(stored) : null;
+    } catch (error) {
+      return null;
+    }
+  }, [persistState, storageKey]);
+
+  // Helper to save state
+  const saveState = React.useCallback((state) => {
+    if (!persistState) return;
+    try {
+      sessionStorage.setItem(storageKey, JSON.stringify(state));
+    } catch (error) {
+      // Silently fail if sessionStorage is not available
+    }
+  }, [persistState, storageKey]);
+
+  // Initialize state from persisted data or props
+  const persistedState = loadPersistedState();
+  
+  const [page, setPage] = React.useState(persistedState?.page || initialPage);
+  const [sortBy, setSortBy] = React.useState(
+    persistedState?.sortBy || initialSortBy || (columns.find((c) => c.sortable)?.field) || "",
+  );
+  const [sortOrder, setSortOrder] = React.useState(persistedState?.sortOrder || initialSortOrder);
+  const [search, setSearch] = React.useState(persistedState?.search || initialSearch || "");
+  const [statusFilter, setStatusFilter] = React.useState(persistedState?.statusFilter || initialStatusFilter || "all");
+  const [limit, setLimit] = React.useState(persistedState?.limit || initialLimit || 10);
+  const [data, setData] = React.useState([]);
+  const [loading, setLoading] = React.useState(false);
+  const [totalPages, setTotalPages] = React.useState(1);
+  const [totalItems, setTotalItems] = React.useState(0);
+  // Column search state
+  const [columnSearch, setColumnSearch] = React.useState(persistedState?.columnSearch || {});
+  
+  // Save state whenever it changes
+  React.useEffect(() => {
+    saveState({
+      page,
+      sortBy,
+      sortOrder,
+      search,
+      statusFilter,
+      limit,
+      columnSearch,
+    });
+  }, [page, sortBy, sortOrder, search, statusFilter, limit, columnSearch, saveState]);
+
   const handleStatusToggle = async (row) => {
     if (!toggleLink) return;
     try {
@@ -81,21 +146,6 @@ export function DataTable(props) {
       toast.error(error.message || "Failed to update status");
     }
   };
-
-  const [page, setPage] = React.useState(initialPage);
-  const [sortBy, setSortBy] = React.useState(
-    initialSortBy || (columns.find((c) => c.sortable)?.field) || "",
-  );
-  const [sortOrder, setSortOrder] = React.useState(initialSortOrder);
-  const [search, setSearch] = React.useState(initialSearch || "");
-  const [statusFilter, setStatusFilter] = React.useState(initialStatusFilter || "all");
-  const [limit, setLimit] = React.useState(initialLimit || 10);
-  const [data, setData] = React.useState([]);
-  const [loading, setLoading] = React.useState(false);
-  const [totalPages, setTotalPages] = React.useState(1);
-  const [totalItems, setTotalItems] = React.useState(0);
-  // Column search state
-  const [columnSearch, setColumnSearch] = React.useState({});
   
   // Reset page to 1 when columnSearch changes
   React.useEffect(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vasuzex",
-  "version": "2.2.4",
+  "version": "2.3.1",
   "description": "Laravel-inspired framework for Node.js monorepos - V2 with optimized dependencies",
   "type": "module",
   "main": "./framework/index.js",