xypriss 9.0.13 → 9.1.1

package/docs/config/CONFIGS_API.md

@@ -0,0 +1,414 @@
+# XyPriss Configs API
+
+A safe, singleton-based configuration manager for XyPriss that solves the "cannot access before initialization" error in modular structures.
+
+## The Problem
+
+When using XyPriss in a modular structure, accessing `app.configs` directly can cause initialization timing issues:
+
+```typescript
+import { createServer } from "xypriss";
+import { FileUploadAPI } from "xypriss";
+
+const app = createServer({
+    /* ... */
+});
+
+// ❌ This might fail with "cannot access app before initialization"
+const upload = new FileUploadAPI();
+await upload.initialize(app.configs?.fileUpload);
+```
+
+## The Solution
+
+The `Configs` API provides a global, singleton-based configuration store that's automatically populated when you create a server:
+
+```typescript
+import { createServer, Configs } from "xypriss";
+import { FileUploadAPI } from "xypriss";
+
+const app = createServer({
+    /* ... */
+});
+
+// ✅ Pass the Configs class - it accesses config internally
+// This enforces a single source of truth
+const upload = new FileUploadAPI();
+await upload.initialize(Configs);
+```
+
+**Why pass the Configs class?**
+
+- ✅ Single source of truth - no config conflicts
+- ✅ Modular - update config once, changes everywhere
+- ✅ Easy to debug - all config in one place
+- ✅ Type-safe - enforced by TypeScript
+
+## Installation
+
+The Configs API is built into XyPriss. Just import it:
+
+```typescript
+import { Configs }Uploadpriss";
+```
+
+## API Reference
+
+### `Configs.set(config: ServerOptions)`
+
+Set the entire configuration. This is automatically called by `createServer()`.
+
+```typescript
+Configs.set({
+    server: { port: 3000 },
+    fileUpload: { enabled: true },
+});
+```
+
+### `Configs.get<K>(key: K): ServerOptions[K] | undefined`
+
+Get a specific configuration section.
+
+```typescript
+const fileUploadConfig = Configs.get("fileUpload");
+const securityConfig = Configs.get("security");
+const serverConfig = Configs.get("server");
+```
+
+### `Configs.getAll(): ServerOptions`
+
+Get the entire configuration object.
+
+```typescript
+const allConfigs = Configs.getAll();
+console.log(allConfigs);
+```
+
+### `Configs.update<K>(key: K, value: ServerOptions[K])`
+
+Update a specific configuration section.
+
+```typescript
+Configs.update("fileUpload", {
+    enabled: true,
+    maxFileSize: 20 * 1024 * 1024,
+});
+```
+
+### `Configs.merge(config: Partial<ServerOptions>)`
+
+Merge configuration with existing config (deep merge for nested objects).
+
+```typescript
+Configs.merge({
+    fileUpload: {
+        maxFileSize: 15 * 1024 * 1024,
+        // Other properties are preserved
+    },
+    performance: {
+        optimizationEnabled: true,
+    },
+});
+```
+
+### `Configs.has<K>(key: K): boolean`
+
+Check if a specific configuration section exists.
+
+```typescript
+if (Configs.has("fileUpload")) {
+    console.log("File upload is configured");
+}
+```
+
+### `Configs.isInitialized(): boolean`
+
+Check if configuration has been initialized.
+
+```typescript
+if (Configs.isInitialized()) {
+    console.log("Configs are ready to use");
+}
+```
+
+### `Configs.getOrDefault<K>(key: K, defaultValue: ServerOptions[K]): ServerOptions[K]`
+
+Get configuration with a default value if not set.
+
+```typescript
+const monitoringConfig = Configs.getOrDefault("monitoring", {
+    enabled: true,
+    healthChecks: true,
+});
+```
+
+### `Configs.delete<K>(key: K)`
+
+Delete a specific configuration section.
+
+```typescript
+Configs.delete("fileUpload");
+```
+
+### `Configs.reset()`
+
+Reset configuration to empty state (useful for testing).
+
+```typescript
+Configs.reset();
+```
+
+## Usage Examples
+
+### BUploade
+
+```typescript
+import { createServer, Configs } from "xypriss";
+import { FileUploadAPI } from "xypriss";
+Upload
+const app = createServer({
+    server: { port: Upload
+    fileUpload: {
+        enabled: true,
+        maxFileSize: 10 * 1024 * 1024,
+    },
+});
+
+// Initialize services by passing Configs class
+const upload = new FileUploadAPI();
+await upload.initialize(Configs);
+
+// Access configuration when needed
+const fileUploadConfig = Configs.get("fileUpload");
+console.log(fileUploadConfig);
+```
+
+### Modular Service Pattern
+
+```typescript
+import { Configs } from "xypriss";
+import { FileUploadAPI, Upload } from "xypriss";
+
+class FileService {
+    private upload: FileUploadAPI;
+
+    constructor() {
+        this.upload = new FileUploadAPI(); // or use the Upload class directly "this.upload = Upload"
+    }
+
+    async initialize() {
+        // Pass Configs class - it accesses config internally
+        // Single source of truth - no config conflicts
+        await this.upload.initialize(Configs);
+
+        // Access config when needed for validation
+        const config = Configs.get("fileUpload");
+        if (!config?.enabled) {
+            throw new Error("File upload is not enabled");
+        }
+    }
+}
+```
+
+### Conditional Configuration
+
+```typescript
+import { Configs } from "xypriss";
+
+function setupMiddleware(app: any) {
+    const securityConfig = Configs.get("security");
+    const performanceConfig = Configs.get("performance");
+
+    if (securityConfig?.enabled) {
+        app.middleware().security(securityConfig);
+    }
+
+    if (performanceConfig?.optimizationEnabled) {
+        // Enable optimizations
+    }
+}
+```
+
+### Environment-Specific Configuration
+
+```typescript
+import { Configs } from "xypriss";
+
+const env = process.env.NODE_ENV || "development";
+
+if (env === "production") {
+    Configs.merge({
+        security: {
+            enabled: true,
+            level: "maximum",
+        },
+        performance: {
+            optimizationEnabled: true,
+            aggressiveCaching: true,
+        },
+    });
+}
+```
+
+### Dynamic Updates
+
+```typescript
+import { Configs } from "xypriss";
+
+function updateMaxFileSize(newSize: number) {
+    const currentConfig = Configs.get("fileUpload");
+
+    if (currentConfig) {
+        Configs.update("fileUpload", {
+            ...currentConfig,
+            maxFileSize: newSize,
+        });
+    }
+}
+```
+
+### Configuration Validation
+
+```typescript
+import { Configs } from "xypriss";
+
+function validateConfigs() {
+    const required = ["server", "security"] as const;
+
+    for (const key of required) {
+        if (!Configs.has(key)) {
+            throw new Error(`Missing required configuration: ${key}`);
+        }
+    }
+}
+```
+
+### Using in Route Handlers
+
+```typescript
+import { createServer, Configs } from "xypriss";
+
+const app = createServer({
+    /* ... */
+});
+
+app.get("/config/status", (req, res) => {
+    res.json({
+        initialized: Configs.isInitialized(),
+        fileUploadEnabled: Configs.get("fileUpload")?.enabled ?? false,
+        securityLevel: Configs.get("security")?.level ?? "none",
+    });
+});
+
+app.get("/config/all", (req, res) => {
+    res.json(Configs.getAll());
+});
+```
+
+## Available Configuration Keys
+
+The `Configs` API supports all `ServerOptions` keys:
+
+- `env` - Environment mode
+- `cache` - Cache configuration
+- `performance` - Performance optimization settings
+- `monitoring` - Monitoring configuration
+- `server` - Server settings (port, host, etc.)
+- `multiServer` - Multi-server configuration
+- `requestManagement` - Request management settings
+- `fileUpload` - File upload configuration
+- `security` - Security settings
+- `cluster` - Cluster configuration
+- `logging` - Logging configuration
+- `middleware` - Middleware configuration
+
+## TypeScript Support
+
+The Configs API is fully typed with TypeScript:
+
+```typescript
+import { Configs, ConfigKey } from "xypriss";
+
+// Type-safe key access
+const key: ConfigKey = "fileUpload";
+const config = Configs.get(key);
+
+// Autocomplete support
+Configs.get("fileUpload"); // ✅ Autocomplete works
+Configs.get("invalid"); // ❌ TypeScript error
+```
+
+## Best Practices
+
+1. **Use `Configs.get()` in modular code** to avoid initialization timing issues
+2. **Check existence with `Configs.has()`** before accessing optional configurations
+3. **Use `Configs.getOrDefault()`** for configurations with sensible defaults
+4. **Validate configurations** at startup using `Configs.has()` or custom validation
+5. **Use `Configs.merge()`** instead of `Configs.set()` when updating partial configurations
+6. **Access `app.configs` directly** only when you're certain the app is initialized
+
+## Migration Guide
+
+### Before (with initialization issues)
+
+```typescript
+import { createServer } from 'xypriss';
+import { FileUploadAPI } from 'xypriss';
+
+const app = createServer({ /* ... */ });
+
+// ❌ Might fail - initialization timing issues
+const upload = new FileUploadAPI();
+await upload.initialize(app.configs?.fileUpload);
+
+// ❌ Also bad - potential config conflicts
+await upload.initialize({ enabled: true, maxFileSize: 5MB });
+```
+
+### After (with Configs API)
+
+```typescript
+import { createServer, Configs } from "xypriss";
+import { FileUploadAPI } from "xypriss";
+
+const app = createServer({
+    fileUpload: {
+        enabled: true,
+        maxFileSize: 5 * 1024 * 1024,
+    },
+});
+
+// ✅ Single source of truth - pass Configs class
+const upload = new FileUploadAPI();
+await upload.initialize(Configs);
+
+// ✅ Update config in one place, changes everywhere
+Configs.update("fileUpload", { maxFileSize: 10 * 1024 * 1024 });
+```
+
+## FAQ
+
+### Q: When should I use `Configs.get()` vs `app.configs`?
+
+**A:** Use `Configs.get()` in modular code where initialization timing might be an issue. Use `app.configs` when you're certain the app is initialized (e.g., in route handlers).
+
+### Q: Is the configuration reactive?
+
+**A:** No, the configuration is not reactive. If you update the configuration with `Configs.update()` or `Configs.merge()`, existing code won't automatically pick up the changes. You'll need to re-read the configuration.
+
+### Q: Can I use Configs before calling createServer()?
+
+**A:** Yes, but the configuration will be empty until `createServer()` is called. You can manually populate it with `Configs.set()` if needed.
+
+### Q: Is Configs thread-safe?
+
+**A:** The Configs singleton is designed for single-threaded Node.js environments. For multi-process setups (e.g., cluster mode), each process will have its own Configs instance.
+
+### Q: Can I reset the configuration?
+
+**A:** Yes, use `Configs.reset()` to clear all configurations. This is mainly useful for testing.
+
+## License
+
+Nehonix OSL (NOSL)- Part of the XyPriss framework
+

package/docs/config/CONFIGS_QUICK_REFERENCE.md

@@ -0,0 +1,124 @@
+# Configs API - Quick Reference
+
+## Import
+
+```typescript
+import { Configs }Uploadpriss";
+import type { ConfigKey, FileUploadConfig } from "xypriss";
+```
+
+## Basic Usage
+
+```typescript
+// Get configuration (type-safe)
+const config = Configs.get("fileUpload");
+
+// Get with default
+const config = Configs.getOrDefault("fileUpload", { enabled: false });
+
+// Check existence
+if (Configs.has("fileUpload")) {
+    /* ... */
+}
+
+// Get all configs
+const all = Configs.getAll();
+```
+
+## Type-Safe File Upload
+
+```typescript
+import { FileUploadAPI } from "xypriss";
+import type { FileUploadConfig } from "xypriss";
+
+const upload = new FileUploadAPI();
+const config: FileUploadConfig | undefined = Configs.get("fileUpload");
+await upload.initialize(config);
+```
+
+## Update Configuration
+
+```typescript
+// Update specific section
+Configs.update("fileUpload", {
+    enabled: true,
+    maxFileSize: 20 * 1024 * 1024,
+});
+
+// Merge (deep merge for nested objects)
+Configs.merge({
+    fileUpload: { maxFileSize: 15 * 1024 * 1024 },
+});
+
+// Set entire config
+Configs.set({ server: { port: 3000 } });
+```
+
+## Available Keys
+
+-   `env` - Environment mode
+-   `cache` - Cache configuration
+-   `performance` - Performance settings
+-   `monitoring` - Monitoring config
+-   `server` - Server settings
+-   `multiServer` - Multi-server config
+-   `requestManagement` - Request management
+-   `fileUpload` - File upload config ⭐
+-   `security` - Security settings
+-   `cluster` - Cluster config
+-   `logging` - Logging config
+-   `middleware` - Middleware config
+
+## Common Patterns
+
+### Pattern 1: Modular Service
+
+```typescript
+class MyService {
+    async initialize() {
+        const config = Configs.get("fileUpload");
+        if (!config?.enabled) throw new Error("Not enabled");
+        // Use config...
+    }
+}
+```
+
+### Pattern 2: Validation
+
+```typescript
+function validate() {
+    const required: Array<keyof ServerOptions> = ["server", "security"];
+    return required.every((key) => Configs.has(key));
+}
+```
+
+### Pattern 3: Conditional Setup
+
+```typescript
+const security = Configs.get("security");
+if (security?.enabled) {
+    app.middleware().security(security);
+}
+```
+
+## Migration
+
+**Before:**
+
+```typescript
+await upload.initialize(app.configs?.fileUpload); // ❌ May fail
+```
+
+**After:**
+
+```typescript
+await upload.initialize(Configs.get("fileUpload")); // ✅ Type-safe
+```
+
+## See Also
+
+-   `docs/CONFIGS_API.md` - Full documentation
+-   `docs/CONFIGS_IMPLEMENTATION.md` - Implementation details
+-   `.private/configs-example.ts` - Comprehensive examples
+-   `.private/type-safe-configs.ts` - Type-safe examples
+

package/docs/config/META_CONFIG.md

@@ -0,0 +1,65 @@
+# Meta Configuration System
+
+The XyPriss Meta Configuration system provides a mechanism for executing arbitrary TypeScript or JavaScript code during the server initialization phase. This feature is designed for advanced setup tasks that require programmatic logic before the standard configuration is applied.
+
+## Overview
+
+The Meta Configuration system automatically detects and executes specific files located within the project structure. It is triggered by the `ConfigLoader` before the standard `xypriss.config.json` is processed, ensuring that any global state or environment adjustments are in place early in the lifecycle.
+
+## File Discovery
+
+The system searches for a single meta configuration file in the following locations (in order of priority):
+
+1. `+xypriss.meta.ts` (Project Root)
+2. `+xypriss.meta.js` (Project Root)
+3. `.meta/+xypriss.meta.js`
+4. `.meta/+xypriss.meta.ts`
+5. `.xypriss/+xypriss.meta.ts`
+6. `.xypriss/+xypriss.meta.js`
+
+Only the first file found in this list will be executed.
+
+## Execution Mechanism
+
+The Meta Configuration file supports two methods of execution:
+
+### 1. Immediate Execution (IIFE)
+
+Any code placed at the top level of the file or within an Immediately Invoked Function Expression (IIFE) will execute as soon as the file is imported by the system.
+
+### 2. The `run` Function
+
+If the file exports a function named `run`, the system will automatically invoke it after the file has been imported. This is the recommended way to structure complex initialization logic.
+
+## Usage Example
+
+Below is an example of a `+xypriss.meta.ts` file demonstrating both execution methods:
+
+```typescript
+// This code executes immediately upon import
+(() => {
+    console.log("Initializing environment variables...");
+    process.env.CUSTOM_VAR = "initialized";
+})();
+
+/**
+ * The run function is called automatically by the ConfigLoader.
+ * Use this for structured initialization logic.
+ */
+export function run() {
+    console.log("Executing meta configuration logic...");
+
+    // Example: Modifying global state or performing pre-flight checks
+    if (globalThis.__sys__) {
+        // Perform advanced system adjustments
+    }
+}
+```
+
+## Technical Details
+
+-   **Execution Timing**: The meta configuration is executed during the call to `configLoader.loadAndApplySysConfig()`, which typically occurs at the very beginning of the server creation process.
+-   **Singleton Execution**: The system includes an internal guard to ensure that the meta configuration is only executed once per process lifetime, preventing side effects during configuration reloads.
+-   **Error Handling**: Errors occurring during the import or execution of the meta file are caught and logged as warnings to prevent the main application from crashing during startup.
+-   **Environment Support**: The system supports both TypeScript (.ts) and JavaScript (.js) files, leveraging dynamic imports for execution.
+