xypriss 4.5.0 → 4.6.0

package/dist/index.d.ts

@@ -4090,6 +4090,261 @@ declare class XyPrissSys {
      */
     $clone(): XyPrissSys;
 }
+/**
+ * Default instance for easy access
+ */
+declare const __sys__: XyPrissSys;
+
+/**
+ * XyPriss Configuration Manager
+ *
+ * Provides a safe way to access and update XyPriss configurations
+ * without encountering "cannot access before initialization" errors.
+ *
+ * This class acts as a singleton configuration store that can be used
+ * in modular structures where accessing `app.configs` directly might
+ * cause initialization timing issues.
+ *
+ * **IMPORTANT**: This is the SINGLE SOURCE OF TRUTH for all XyPriss configurations.
+ * All components should use `Configs.get()` to access configuration values
+ * instead of copying values during initialization.
+ *
+ * @example
+ * ```typescript
+ * import { Configs } from 'xypriss';
+ *
+ * // Set configuration
+ * Configs.set({
+ *   fileUpload: {
+ *     enabled: true,
+ *     maxFileSize: 5 * 1024 * 1024
+ *   }
+ * });
+ *
+ * // Get configuration
+ * const fileUploadConfig = Configs.get('fileUpload');
+ *
+ * // Get entire config
+ * const allConfigs = Configs.getAll();
+ *
+ * // Update specific config (updates the source of truth)
+ * Configs.update('fileUpload', { maxFileSize: 10 * 1024 * 1024 });
+ * ```
+ */
+
+/**
+ * Configuration Manager Class
+ * Singleton pattern for managing XyPriss configurations
+ */
+declare class ConfigurationManager {
+    private static instance;
+    private config;
+    private initialized;
+    /**
+     * Private constructor to enforce singleton pattern
+     * Initializes with default configuration
+     */
+    private constructor();
+    /**
+     * Get the singleton instance
+     */
+    private static getInstance;
+    /**
+     * Set the entire configuration
+     * @param config - XP Server configuration options
+     */
+    static set(config: ServerOptions): void;
+    /**
+     * Get a specific configuration section
+     * @param key - Configuration key (e.g., 'fileUpload', 'security', 'cache')
+     * @returns The configuration value for the specified key
+     */
+    static get<K extends keyof ServerOptions>(key: K): ServerOptions[K];
+    /**
+     * Get the entire configuration object
+     * @returns Complete XyPriss Server Configuration (XPSC)
+     */
+    static getAll(): ServerOptions;
+    /**
+     * Update a specific XyPriss configuration section (deep merge)
+     * @param key - Configuration key to update
+     * @param value - Partial value to merge with existing configuration
+     */
+    static update<K extends keyof ServerOptions>(key: K, value: Partial<ServerOptions[K]>): void;
+    /**
+     * Deep merge helper function
+     * @param target - Target object
+     * @param source - Source object to merge
+     * @returns Merged object
+     */
+    private static deepMerge;
+    /**
+     * Merge configuration with existing config (deep merge)
+     * @param config - Partial configuration to merge
+     */
+    static merge(config: Partial<ServerOptions>): void;
+    /**
+     * Check if configuration has been initialized
+     * @returns true if configuration has been set, false otherwise
+     */
+    static isInitialized(): boolean;
+    /**
+     * Reset configuration to empty state
+     * Useful for testing or reinitializing
+     */
+    static reset(): void;
+    /**
+     * Check if a specific configuration section exists
+     * @param key - Configuration key to check
+     * @returns true if the configuration section exists
+     */
+    static has<K extends keyof ServerOptions>(key: K): boolean;
+    /**
+     * Get configuration with a default value if not set
+     * @param key - Configuration key
+     * @param defaultValue - Default value to return if key doesn't exist
+     * @returns Configuration value or default value
+     */
+    static getOrDefault<K extends keyof ServerOptions>(key: K, defaultValue: ServerOptions[K]): ServerOptions[K];
+    /**
+     * Delete a specific configuration section
+     * @param key - Configuration key to delete
+     */
+    static delete<K extends keyof ServerOptions>(key: K): void;
+}
+
+/**
+ * Default instance for easy access
+ */
+declare const __cfg__: typeof ConfigurationManager;
+
+/**************************************************************************************************************************************************************
+ * This code contains proprietary source code from NEHONIX
+ *
+ * @author Nehonix
+ * @license NOSL
+ * @version v1.0
+ * @see {@link https://dll.nehonix.com/licenses/NOSL}
+ *
+ * Copyright (c) 2025 Nehonix. All rights reserved.
+ *
+ *
+ * This License governs the use, modification, and distribution of software provided by NEHONIX under its open source projects.
+ * NEHONIX is committed to fostering collaborative innovation while strictly protecting its intellectual property rights.
+ * Violation of any term of this License will result in immediate termination of all granted rights and may subject the violator to legal action.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+ * IN NO EVENT SHALL NEHONIX BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING FROM THE USE
+ * OR INABILITY TO USE THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+ ************************************************************************************************************************************************************** */
+/**
+ * XyPriss Constant Variables Class
+ *
+ * Provides a mechanism to store immutable values that cannot be changed once set.
+ * This is useful for protecting critical application constants from being
+ * modified by plugins or other modules at runtime.
+ *
+ * @class XyPrissConst
+ * @version 2.0.0
+ */
+declare class XyPrissConst {
+    private constants;
+    private immutableCache;
+    /**
+     * Make a value deeply immutable using Proxy protection.
+     * This ACTIVELY blocks any modification attempts with clear error messages.
+     * Works with objects, arrays, Maps, Sets, and nested structures.
+     *
+     * @template T - Type of the value to freeze
+     * @param {T} value - The value to make immutable
+     * @param {string} [path] - Internal path tracking for error messages
+     * @returns {T} The deeply protected immutable value
+     *
+     * @example
+     * ```typescript
+     * const config = __const__.$make({
+     *   server: { port: 8080, host: 'localhost' },
+     *   features: ['auth', 'logging']
+     * });
+     * config.server.port = 9000; // ❌ THROWS ERROR IMMEDIATELY
+     * ```
+     */
+    $make<T>(value: T, path?: string): T;
+    /**
+     * Define a new constant.
+     * Throws an error if the constant is already defined.
+     * Automatically makes the value deeply immutable.
+     *
+     * @param {string} key - The unique identifier for the constant
+     * @param {any} value - The value to store (will be made immutable)
+     * @throws {Error} If the key already exists
+     *
+     * @example
+     * ```typescript
+     * __const__.$set('APP_CONFIG', {
+     *   database: { host: 'localhost', port: 5432 }
+     * });
+     * ```
+     */
+    $set(key: string, value: any): void;
+    /**
+     * Retrieve a constant value.
+     *
+     * @template T - Expected type of the constant
+     * @param {string} key - The identifier of the constant
+     * @param {T} [defaultValue] - Optional fallback value if not found
+     * @returns {T} The constant value or default
+     *
+     * @example
+     * ```typescript
+     * const appId = __const__.$get('APP_ID');
+     * ```
+     */
+    $get<T = any>(key: string, defaultValue?: T): T;
+    /**
+     * Check if a constant is defined.
+     *
+     * @param {string} key - The identifier to check
+     * @returns {boolean} True if the constant exists
+     */
+    $has(key: string): boolean;
+    /**
+     * Export all constants as a plain object.
+     * Note: Returns a frozen snapshot, not the proxy-protected originals.
+     *
+     * @returns {Record<string, any>}
+     */
+    $toJSON(): Record<string, any>;
+    /**
+     * Delete a constant (use with extreme caution).
+     * This is primarily for testing purposes.
+     *
+     * @param {string} key - The identifier to delete
+     * @returns {boolean} True if the constant was deleted
+     */
+    $delete(key: string): boolean;
+    /**
+     * Clear all constants (use with extreme caution).
+     * This is primarily for testing purposes.
+     */
+    $clear(): void;
+    /**
+     * Get the total number of constants stored.
+     *
+     * @returns {number} The count of constants
+     */
+    $size(): number;
+    /**
+     * List all constant keys.
+     *
+     * @returns {string[]} Array of all constant keys
+     */
+    $keys(): string[];
+}
+/**
+ * Default instance for easy access
+ */
+declare const __const__: XyPrissConst;
 
 /**
  * @fileoverview Main export file for XyPrissJS Express integration types
@@ -4116,30 +4371,102 @@ declare class XyPrissSys {
  */
 
 declare global {
-    const Bun: {
-        spawn: (options: {
-            cmd: string[];
-            env?: Record<string, string>;
-            stdio?: string[];
-        }) => BunSubprocess;
-    };
     /**
-     * Provides centralized access to system variables, configuration management, and environment utilities for XyPriss applications.
-     * This module serves as a type-safe wrapper around system configuration with built-in helpers for common operations.
+     * **XyPriss System Variables Manager (`__sys__`)**
+     *
+     * Provides centralized access to system-level variables, environment detection, and dynamic
+     * configuration management. This global instance serves as a type-safe wrapper around
+     * application metadata and environment utilities.
+     *
+     * @global
+     * @type {XyPrissSys}
+     *
+     * @example
+     * ```typescript
+     * // Environment Detection
+     * if (__sys__.$isProduction()) {
+     *   console.log("Running in production mode");
+     * }
+     *
+     * // Dynamic Variable Management
+     * __sys__.$add("appName", "MyXyPrissApp");
+     * const version = __sys__.$get("version", "1.0.0");
+     *
+     * // Bulk Update
+     * __sys__.$update({
+     *   author: "Nehonix",
+     *   debug: true
+     * });
+     * ```
+     *
+     * @see {@link https://github.com/Nehonix-Team/XyPriss/blob/master/docs/features/sys-globals.md}
      */
     var __sys__: XyPrissSys;
+    /**
+     * **XyPriss Configuration Manager (`__cfg__`)**
+     *
+     * A singleton interface for managing the core XyPriss server configuration.
+     * It handles deep merging of options, default values, and provides a single source
+     * of truth for all server components (security, performance, routing, etc.).
+     *
+     * @global
+     * @type {typeof Configs}
+     *
+     * @example
+     * ```typescript
+     * // Accessing Configuration
+     * const serverPort = __cfg__.get("server")?.port;
+     * const isSecurityEnabled = __cfg__.get("security")?.enabled;
+     *
+     * // Updating Configuration (Deep Merge)
+     * __cfg__.update("performance", {
+     *   slowRequestThreshold: 1000
+     * });
+     *
+     * // Check Initialization State
+     * if (__cfg__.isInitialized()) {
+     *   console.log("Server configuration is ready");
+     * }
+     * ```
+     *
+     * @see {@link https://github.com/Nehonix-Team/XyPriss/blob/master/docs/CFG_API.md}
+     */
+    var __cfg__: typeof ConfigurationManager;
+    /**
+     * **XyPriss Immutable Constants (`__const__`)**
+     *
+     * A global registry for immutable application constants. Once a value is set
+     * via `__const__.$set()`, it cannot be modified or redefined, ensuring
+     * data integrity across the entire application lifecycle.
+     *
+     * @global
+     * @type {XyPrissConst}
+     *
+     * @example
+     * ```typescript
+     * // Defining a constant (only once)
+     * __const__.$set('SERVER_PORT', 8080);
+     *
+     * // Attempting to redefine will throw an error
+     * try {
+     *   __const__.$set('SERVER_PORT', 9000);
+     * } catch (e) {
+     *   console.error(e.message); // Cannot redefine constant "SERVER_PORT"
+     * }
+     *
+     * // Accessing a constant
+     * const port = __const__.$get('SERVER_PORT');
+     *
+     * // Making an object deeply immutable
+     * const config = __const__.$make({ port: 8080 });
+     * config.port = 9000; // Throws error!
+     * ```
+     *@see {@link https://github.com/Nehonix-Team/XyPriss/blob/master/docs/CONST_API.md}
+     * @see {@link https://github.com/Nehonix-Team/XyPriss/blob/master/docs/GLOBAL_APIS.md}
+     */
+    var __const__: XyPrissConst;
 }
 
-type BunSubprocess = {
-    exited: Promise<number | null>;
-    kill: (signal?: string) => void;
-    killed: boolean;
-    pid: number;
-    stdout?: ReadableStream<Uint8Array>;
-    stderr?: ReadableStream<Uint8Array>;
-    stdin?: WritableStream<Uint8Array>;
-};
-
 /**
  * XyPrissJS Cluster Manager
  *  cluster management for Express applications with advanced monitoring
@@ -8014,124 +8341,6 @@ interface FileUploadConfig {
     };
 }
 
-/**
- * XyPriss Configuration Manager
- *
- * Provides a safe way to access and update XyPriss configurations
- * without encountering "cannot access before initialization" errors.
- *
- * This class acts as a singleton configuration store that can be used
- * in modular structures where accessing `app.configs` directly might
- * cause initialization timing issues.
- *
- * **IMPORTANT**: This is the SINGLE SOURCE OF TRUTH for all XyPriss configurations.
- * All components should use `Configs.get()` to access configuration values
- * instead of copying values during initialization.
- *
- * @example
- * ```typescript
- * import { Configs } from 'xypriss';
- *
- * // Set configuration
- * Configs.set({
- *   fileUpload: {
- *     enabled: true,
- *     maxFileSize: 5 * 1024 * 1024
- *   }
- * });
- *
- * // Get configuration
- * const fileUploadConfig = Configs.get('fileUpload');
- *
- * // Get entire config
- * const allConfigs = Configs.getAll();
- *
- * // Update specific config (updates the source of truth)
- * Configs.update('fileUpload', { maxFileSize: 10 * 1024 * 1024 });
- * ```
- */
-
-/**
- * Configuration Manager Class
- * Singleton pattern for managing XyPriss configurations
- */
-declare class ConfigurationManager {
-    private static instance;
-    private config;
-    private initialized;
-    /**
-     * Private constructor to enforce singleton pattern
-     * Initializes with default configuration
-     */
-    private constructor();
-    /**
-     * Get the singleton instance
-     */
-    private static getInstance;
-    /**
-     * Set the entire configuration
-     * @param config - XP Server configuration options
-     */
-    static set(config: ServerOptions): void;
-    /**
-     * Get a specific configuration section
-     * @param key - Configuration key (e.g., 'fileUpload', 'security', 'cache')
-     * @returns The configuration value for the specified key
-     */
-    static get<K extends keyof ServerOptions>(key: K): ServerOptions[K];
-    /**
-     * Get the entire configuration object
-     * @returns Complete XyPriss Server Configuration (XPSC)
-     */
-    static getAll(): ServerOptions;
-    /**
-     * Update a specific XyPriss configuration section (deep merge)
-     * @param key - Configuration key to update
-     * @param value - Partial value to merge with existing configuration
-     */
-    static update<K extends keyof ServerOptions>(key: K, value: Partial<ServerOptions[K]>): void;
-    /**
-     * Deep merge helper function
-     * @param target - Target object
-     * @param source - Source object to merge
-     * @returns Merged object
-     */
-    private static deepMerge;
-    /**
-     * Merge configuration with existing config (deep merge)
-     * @param config - Partial configuration to merge
-     */
-    static merge(config: Partial<ServerOptions>): void;
-    /**
-     * Check if configuration has been initialized
-     * @returns true if configuration has been set, false otherwise
-     */
-    static isInitialized(): boolean;
-    /**
-     * Reset configuration to empty state
-     * Useful for testing or reinitializing
-     */
-    static reset(): void;
-    /**
-     * Check if a specific configuration section exists
-     * @param key - Configuration key to check
-     * @returns true if the configuration section exists
-     */
-    static has<K extends keyof ServerOptions>(key: K): boolean;
-    /**
-     * Get configuration with a default value if not set
-     * @param key - Configuration key
-     * @param defaultValue - Default value to return if key doesn't exist
-     * @returns Configuration value or default value
-     */
-    static getOrDefault<K extends keyof ServerOptions>(key: K, defaultValue: ServerOptions[K]): ServerOptions[K];
-    /**
-     * Delete a specific configuration section
-     * @param key - Configuration key to delete
-     */
-    static delete<K extends keyof ServerOptions>(key: K): void;
-}
-
 /**
  * Initialize the global file upload manager (legacy)
  * This is called automatically when the server starts with file upload enabled
@@ -13311,5 +13520,5 @@ declare class TrustProxy {
  */
 declare function Router(): XyPrissRouter;
 
-export { ConfigurationManager as CM, CachePlugin as CachePluginBase, CompressionPlugin, ConfigurationManager as Configs, ConnectionPlugin, DEFAULT_PLUGIN_CONFIG, FileUploadAPI as FLA, FileUploadAPI, JWTAuthPlugin, NetworkCategory, NetworkPlugin, NetworkPluginFactory, NetworkPluginUtils, PERFORMANCE_TARGETS, PLUGIN_SYSTEM_NAME, PLUGIN_SYSTEM_VERSION, PerformanceMonitor, PerformancePlugin as PerformancePluginBase, Plugin, PluginDevelopmentHelpers, PluginEngine, PluginEventType, PluginPriority, PluginRegistry, PluginSystemFactory, PluginSystemUtils, PluginType, ProxyPlugin, RateLimitPlugin, ResponseTimePlugin, Route, Router, SecurityMiddleware, SecurityPlugin as SecurityPluginBase, SmartCachePlugin, TrustProxy, Upload, XJsonResponseHandler, XyPrissRouter, createCacheMiddleware, createCircularRefDebugger, createOptimalCache, createSafeJsonMiddleware, createServer, createServerInstance, expressStringify, fastStringify, initializeFileUpload, quickServer, safeJsonStringify, safeStringify, sendSafeJson, setupSafeJson, uploadAny, uploadArray, uploadFields, uploadSingle };
+export { ConfigurationManager as CM, CachePlugin as CachePluginBase, CompressionPlugin, ConfigurationManager as Configs, ConnectionPlugin, DEFAULT_PLUGIN_CONFIG, FileUploadAPI as FLA, FileUploadAPI, JWTAuthPlugin, NetworkCategory, NetworkPlugin, NetworkPluginFactory, NetworkPluginUtils, PERFORMANCE_TARGETS, PLUGIN_SYSTEM_NAME, PLUGIN_SYSTEM_VERSION, PerformanceMonitor, PerformancePlugin as PerformancePluginBase, Plugin, PluginDevelopmentHelpers, PluginEngine, PluginEventType, PluginPriority, PluginRegistry, PluginSystemFactory, PluginSystemUtils, PluginType, ProxyPlugin, RateLimitPlugin, ResponseTimePlugin, Route, Router, SecurityMiddleware, SecurityPlugin as SecurityPluginBase, SmartCachePlugin, TrustProxy, Upload, XJsonResponseHandler, XyPrissRouter, __cfg__, __const__, __sys__, createCacheMiddleware, createCircularRefDebugger, createOptimalCache, createSafeJsonMiddleware, createServer, createServerInstance, expressStringify, fastStringify, initializeFileUpload, quickServer, safeJsonStringify, safeStringify, sendSafeJson, setupSafeJson, uploadAny, uploadArray, uploadFields, uploadSingle };
 export type { BasePlugin, CacheConfig, CachePlugin$1 as CachePlugin, CompressionAlgorithm, CompressionConfig, ConnectionConfig, FailoverConfig, FileUploadConfig as FiUpConfig, FileUploadConfig, HTTPCacheConfig, HealthCheckConfig, CachePlugin$1 as ICachePlugin, PerformancePlugin$1 as IPerformancePlugin, SecurityPlugin$1 as ISecurityPlugin, LoadBalancingStrategy, MultiServerApp, MultiServerConfig, NativePlugin, NetworkExecutionContext, NetworkExecutionResult, NetworkHealthStatus, NetworkPluginConfig, NetworkSecurityConfig, NextFunction, PerformanceConfig, PerformanceMetrics, PerformancePlugin$1 as PerformancePlugin, PluginConfiguration, PluginCreator, PluginEvent, PluginExecutionContext, PluginExecutionResult, PluginExecutionStats, PluginInitializationContext, PluginRegistryConfig, ProxyConfig, RateLimitConfig, RateLimitRule, RateLimitStrategy, RedisConfig, XyPrisRequest as Request, RequestHandler, XyPrisResponse as Response, RouteConfig, RouteOptions, SecurityConfig, SecurityPlugin$1 as SecurityPlugin, ServerOptions, SmartRouteConfig, TrustProxyValue$1 as TrustProxyValue, UltraFastApp, UpstreamServer, WebSocketConfig, MultiServerApp as XyPMS, XyPrissPlugin, XyPrisRequest as XyPrissRequest, XyPrisResponse as XyPrissResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "xypriss",
-    "version": "4.5.0",
+    "version": "4.6.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",
@@ -271,3 +271,4 @@
         "xypriss-security": "^1.1.14"
     }
 }
+