xypriss 4.3.6 → 4.4.0

package/dist/index.d.ts

@@ -3559,6 +3559,526 @@ interface RouteOptions {
     };
 }
 
+/**
+ * XyPriss System Variables Class
+ *
+ * Provides centralized access to system variables, configuration management,
+ * and environment utilities for XyPriss applications. This class serves as
+ * a type-safe wrapper around system configuration with built-in helpers
+ * for common operations.
+ *
+ * @class XyPrissSys
+ * @version 1.0.0
+ *
+ * @example
+ * ```typescript
+ * // Initialize with default values
+ * const sys = new XyPrissSys({
+ *   __version__: "1.0.0",
+ *   __author__: "John Doe",
+ *   __port__: 8080,
+ *   __env__: "production"
+ * });
+ *
+ * // Check environment
+ * if (__sys__$isProduction()) {
+ *   console.log('Running in production mode');
+ * }
+ *
+ * // Access variables
+ * const port = __sys__$get('__port__', 3000);
+ * ```
+ */
+declare class XyPrissSys {
+    /**
+     * Application version string following semantic versioning.
+     *
+     * @type {string}
+     * @default "0.0.0"
+     *
+     * @example
+     * ```typescript
+     * __sys____version__ = "1.2.3";
+     * console.log(`App version: ${__sys____version__}`);
+     * ```
+     */
+    __version__: string;
+    /**
+     * Application author or maintainer name.
+     *
+     * @type {string}
+     * @default "unknown"
+     *
+     * @example
+     * ```typescript
+     * __sys____author__ = "Jane Smith";
+     * ```
+     */
+    __author__: string;
+    /**
+     * Collection of application URLs for various environments or services.
+     * Useful for storing API endpoints, frontend URLs, or external service links.
+     *
+     * @type {Record<string, string>}
+     * @default {}
+     *
+     * @example
+     * ```typescript
+     * __sys____app_urls__ = {
+     *   api: "https://api.example.com",
+     *   frontend: "https://app.example.com",
+     *   docs: "https://docs.example.com"
+     * };
+     *
+     * const apiUrl = __sys____app_urls__.api;
+     * ```
+     */
+    __app_urls__: Record<string, string>;
+    /**
+     * Application name identifier.
+     *
+     * @type {string}
+     * @default "xypriss-app"
+     *
+     * @example
+     * ```typescript
+     * __sys____name__ = "my-awesome-app";
+     * ```
+     */
+    __name__: string;
+    /**
+     * Application alias or short name.
+     * Used for abbreviated references or CLI commands.
+     *
+     * @type {string}
+     * @default "app"
+     *
+     * @example
+     * ```typescript
+     * __sys____alias__ = "myapp";
+     * ```
+     */
+    __alias__: string;
+    /**
+     * Server port number (lowercase variant).
+     * Synchronized automatically with __PORT__.
+     *
+     * @type {number}
+     * @default 3000
+     *
+     * @example
+     * ```typescript
+     * __sys____port__ = 8080;
+     * console.log(__sys____PORT__); // Also 8080 (auto-synced)
+     * ```
+     */
+    __port__: number;
+    /**
+     * Server port number (uppercase variant).
+     * Synchronized automatically with __port__.
+     *
+     * @type {number}
+     * @default 3000
+     *
+     * @example
+     * ```typescript
+     * __sys____PORT__ = 5000;
+     * console.log(__sys____port__); // Also 5000 (auto-synced)
+     * ```
+     */
+    __PORT__: number;
+    /**
+     * Current environment mode.
+     * Typically "development", "production", "staging", or "test".
+     *
+     * @type {string}
+     * @default "development"
+     *
+     * @example
+     * ```typescript
+     * __sys____env__ = "production";
+     * if (__sys__$isProduction()) {
+     *   // Production-specific logic
+     * }
+     * ```
+     */
+    __env__: string;
+    /**
+     * Environment variables manager providing access to process.env.
+     * Offers a clean API for getting, setting, and managing environment variables.
+     *
+     * @type {Object}
+     * @property {Function} set - Set an environment variable
+     * @property {Function} get - Get an environment variable with optional default
+     * @property {Function} has - Check if an environment variable exists
+     * @property {Function} delete - Remove an environment variable
+     * @property {Function} all - Get all environment variables
+     *
+     * @example
+     * ```typescript
+     * // Set environment variable
+     * __sys____ENV__.set('API_KEY', 'secret123');
+     *
+     * // Get with default
+     * const apiKey = __sys____ENV__.get('API_KEY', 'default-key');
+     *
+     * // Check existence
+     * if (__sys____ENV__.has('DATABASE_URL')) {
+     *   const dbUrl = __sys____ENV__.get('DATABASE_URL');
+     * }
+     *
+     * // Delete variable
+     * __sys____ENV__.delete('TEMP_VAR');
+     *
+     * // Get all variables
+     * const allEnv = __sys____ENV__.all();
+     * ```
+     */
+    __ENV__: {
+        /**
+         * Set an environment variable.
+         *
+         * @param {string} key - The environment variable name
+         * @param {string} value - The value to set
+         * @returns {void}
+         */
+        set: (key: string, value: string) => void;
+        /**
+         * Get an environment variable with an optional default value.
+         *
+         * @param {string} key - The environment variable name
+         * @param {string} [defaultValue] - Default value if variable is not set
+         * @returns {string | undefined} The environment variable value or default
+         */
+        get: (key: string, defaultValue?: string) => string | undefined;
+        /**
+         * Check if an environment variable exists.
+         *
+         * @param {string} key - The environment variable name
+         * @returns {boolean} True if the variable exists
+         */
+        has: (key: string) => boolean;
+        /**
+         * Delete an environment variable.
+         *
+         * @param {string} key - The environment variable name
+         * @returns {void}
+         */
+        delete: (key: string) => void;
+        /**
+         * Get all environment variables.
+         *
+         * @returns {NodeJS.ProcessEnv} All environment variables
+         */
+        all: () => NodeJS.ProcessEnv;
+    };
+    /**
+     * Index signature allowing dynamic property assignment.
+     * Enables flexible extension of system variables at runtime.
+     *
+     * @example
+     * ```typescript
+     * sys['customProperty'] = 'custom value';
+     * __sys__$add('anotherProperty', 123);
+     * ```
+     */
+    [key: string]: any;
+    /**
+     * Creates a new XyPrissSys instance with optional initial data.
+     * All port-related properties are automatically synchronized.
+     *
+     * @constructor
+     * @param {Record<string, any>} [data={}] - Initial system variable data
+     *
+     * @example
+     * ```typescript
+     * // Create with defaults
+     * const sys = new XyPrissSys();
+     *
+     * // Create with custom data
+     * const sys = new XyPrissSys({
+     *   __version__: "2.0.0",
+     *   __author__: "Development Team",
+     *   __port__: 8080,
+     *   __env__: "production",
+     *   customVar: "custom value"
+     * });
+     * ```
+     */
+    constructor(data?: Record<string, any>);
+    /**
+     * Update system variables with new data.
+     * Automatically synchronizes __port__ and __PORT__ to maintain consistency.
+     * Supports backward compatibility for legacy single-underscore variants.
+     *
+     * @param {Record<string, any>} data - Partial data to merge into system variables
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * __sys__$update({
+     *   __version__: "1.5.0",
+     *   __port__: 9000,
+     *   newFeature: true
+     * });
+     *
+     * // Port is automatically synced
+     * console.log(__sys____port__);  // 9000
+     * console.log(__sys____PORT__);  // 9000
+     * ```
+     */
+    $update(data: Record<string, any>): void;
+    /**
+     * Add or update a single system variable.
+     * Provides a cleaner API for adding individual properties.
+     *
+     * @param {string} key - Variable name
+     * @param {any} value - Variable value (any type)
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * __sys__$add('databaseUrl', 'postgresql://localhost:5432/mydb');
+     * __sys__$add('maxConnections', 100);
+     * __sys__$add('features', { darkMode: true, beta: false });
+     *
+     * console.log(__sys__databaseUrl);    // 'postgresql://localhost:5432/mydb'
+     * console.log(__sys__maxConnections); // 100
+     * ```
+     */
+    $add(key: string, value: any): void;
+    /**
+     * Remove a system variable.
+     *
+     * @param {string} key - Variable name to remove
+     * @returns {boolean} True if the variable existed and was removed
+     *
+     * @example
+     * ```typescript
+     * __sys__$add('tempVar', 'temporary');
+     * console.log(__sys__$has('tempVar')); // true
+     *
+     * __sys__$remove('tempVar');
+     * console.log(__sys__$has('tempVar')); // false
+     * ```
+     */
+    $remove(key: string): boolean;
+    /**
+     * Export all system variables as a plain JavaScript object.
+     * Excludes internal methods (starting with $) and the __ENV__ manager.
+     * Useful for serialization, logging, or persistence.
+     *
+     * @returns {Record<string, any>} Plain object containing all system variables
+     *
+     * @example
+     * ```typescript
+     * const config = __sys__$toJSON();
+     * console.log(JSON.stringify(config, null, 2));
+     *
+     * // Save to file
+     * fs.writeFileSync('config.json', JSON.stringify(config, null, 2));
+     *
+     * // Send in API response
+     * res.json({ system: config });
+     * ```
+     */
+    $toJSON(): Record<string, any>;
+    /**
+     * Check if the current environment is production.
+     * Compares __env__ against "production" (case-sensitive).
+     *
+     * @returns {boolean} True if environment is production
+     *
+     * @example
+     * ```typescript
+     * if (__sys__$isProduction()) {
+     *   console.log('Running in production mode');
+     *   // Enable production optimizations
+     *   enableCaching();
+     *   disableDebugMode();
+     * }
+     * ```
+     */
+    $isProduction(): boolean;
+    /**
+     * Check if the current environment is development.
+     * Compares __env__ against "development" (case-sensitive).
+     *
+     * @returns {boolean} True if environment is development
+     *
+     * @example
+     * ```typescript
+     * if (__sys__$isDevelopment()) {
+     *   console.log('Running in development mode');
+     *   // Enable development features
+     *   enableHotReload();
+     *   showDebugInfo();
+     * }
+     * ```
+     */
+    $isDevelopment(): boolean;
+    /**
+     * Check if the current environment is staging.
+     * Compares __env__ against "staging" (case-sensitive).
+     *
+     * @returns {boolean} True if environment is staging
+     *
+     * @example
+     * ```typescript
+     * if (__sys__$isStaging()) {
+     *   console.log('Running in staging mode');
+     *   // Use staging configurations
+     * }
+     * ```
+     */
+    $isStaging(): boolean;
+    /**
+     * Check if the current environment is test.
+     * Compares __env__ against "test" (case-sensitive).
+     *
+     * @returns {boolean} True if environment is test
+     *
+     * @example
+     * ```typescript
+     * if (__sys__$isTest()) {
+     *   console.log('Running in test mode');
+     *   // Use test database
+     *   useTestDatabase();
+     * }
+     * ```
+     */
+    $isTest(): boolean;
+    /**
+     * Check if environment matches a custom environment name.
+     * Performs case-sensitive comparison.
+     *
+     * @param {string} envName - Environment name to check against
+     * @returns {boolean} True if current environment matches the provided name
+     *
+     * @example
+     * ```typescript
+     * if (__sys__$isEnvironment('qa')) {
+     *   console.log('Running in QA environment');
+     * }
+     *
+     * if (__sys__$isEnvironment('local')) {
+     *   // Local development specific code
+     * }
+     * ```
+     */
+    $isEnvironment(envName: string): boolean;
+    /**
+     * Get a system variable with an optional default value.
+     * Type-safe retrieval with generic type parameter support.
+     *
+     * @template T - Expected type of the return value
+     * @param {string} key - Variable name to retrieve
+     * @param {T} [defaultValue] - Default value if variable doesn't exist
+     * @returns {T} The variable value or default value
+     *
+     * @example
+     * ```typescript
+     * // Get with type inference
+     * const port = __sys__$get<number>('__port__', 3000);
+     * const name = __sys__$get<string>('__name__', 'default-app');
+     *
+     * // Get complex types
+     * interface AppConfig {
+     *   theme: string;
+     *   features: string[];
+     * }
+     * const config = __sys__$get<AppConfig>('config', {
+     *   theme: 'light',
+     *   features: []
+     * });
+     *
+     * // Works with undefined variables
+     * const missing = __sys__$get('nonexistent', 'fallback'); // 'fallback'
+     * ```
+     */
+    $get<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * Check if a system variable exists.
+     * Returns true even if the value is falsy (null, false, 0, empty string).
+     *
+     * @param {string} key - Variable name to check
+     * @returns {boolean} True if variable exists (even if falsy)
+     *
+     * @example
+     * ```typescript
+     * __sys__$add('enabled', false);
+     * __sys__$add('count', 0);
+     * __sys__$add('name', '');
+     *
+     * console.log(__sys__$has('enabled')); // true (even though value is false)
+     * console.log(__sys__$has('count'));   // true (even though value is 0)
+     * console.log(__sys__$has('name'));    // true (even though value is '')
+     * console.log(__sys__$has('missing')); // false
+     *
+     * // Conditional logic
+     * if (__sys__$has('apiKey')) {
+     *   const apiKey = __sys__$get('apiKey');
+     *   initializeAPI(apiKey);
+     * }
+     * ```
+     */
+    $has(key: string): boolean;
+    /**
+     * Get all system variable keys.
+     * Excludes internal methods and the __ENV__ manager.
+     *
+     * @returns {string[]} Array of all variable names
+     *
+     * @example
+     * ```typescript
+     * const keys = __sys__$keys();
+     * console.log(keys); // ['__version__', '__author__', '__port__', ...]
+     *
+     * // Iterate over all variables
+     * keys.forEach(key => {
+     *   console.log(`${key}: ${__sys__$get(key)}`);
+     * });
+     * ```
+     */
+    $keys(): string[];
+    /**
+     * Reset all system variables to default values.
+     * Preserves the __ENV__ manager instance.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * __sys__$add('customVar', 'custom');
+     * __sys____version__ = "2.0.0";
+     *
+     * __sys__$reset();
+     *
+     * console.log(__sys____version__);     // "0.0.0" (default)
+     * console.log(__sys__$has('customVar')); // false
+     * ```
+     */
+    $reset(): void;
+    /**
+     * Clone the current system configuration.
+     * Creates a new instance with the same variable values.
+     *
+     * @returns {XyPrissSys} New instance with cloned values
+     *
+     * @example
+     * ```typescript
+     * const sys1 = new XyPrissSys({ __version__: "1.0.0" });
+     * const sys2 = sys1.$clone();
+     *
+     * sys2.__version__ = "2.0.0";
+     *
+     * console.log(sys1.__version__); // "1.0.0" (unchanged)
+     * console.log(sys2.__version__); // "2.0.0"
+     * ```
+     */
+    $clone(): XyPrissSys;
+}
+
 /**
  * @fileoverview Main export file for XyPrissJS Express integration types
  *
@@ -3591,7 +4111,12 @@ declare global {
             stdio?: string[];
         }) => BunSubprocess;
     };
+    /**
+     * Global system variables for XyPriss applications
+     */
+    var __sys__: XyPrissSys;
 }
+
 type BunSubprocess = {
     exited: Promise<number | null>;
     kill: (signal?: string) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xypriss",
-    "version": "4.3.6",
+    "version": "4.4.0",
     "description": "XyPriss is a lightweight, TypeScript-first, open-source Node.js web framework crafted for developers seeking a familiar Express-like API without Express dependencies. It features built-in security middleware, a robust routing system, and performance optimizations to build scalable, secure web applications effortlessly. Join our community and contribute on GitHub!",
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",