Configuration Management
Version Compatibility: XyPriss v6.0.0 and above
Overview
The Configuration Management system in XyPriss provides a centralized, type-safe interface for managing application metadata, runtime settings, and custom configuration values. All configuration is accessible through the global __sys__ instance.
Core Configuration Properties
Application Metadata
__version__
Type: string
Default: "0.0.0"
Description: The semantic version of your application.
__sys__.__version__ = "1.2.3";
console.log(`Running version: ${__sys__.__version__}`);
__name__
Type: string
Default: "xypriss-app"
Description: The application name (kebab-case recommended).
__sys__.__name__ = "my-api-server";
__alias__
Type: string
Default: "app"
Description: Short alias for CLI or logging purposes.
__sys__.__alias__ = "api";
console.log(`[${__sys__.__alias__}] Server started`);
__author__
Type: string
Default: "unknown"
Description: Application author or organization name.
__sys__.__author__ = "Nehonix Team";
__description__
Type: string
Default: "A XyPriss application"
Description: Brief description of the application.
__sys__.__description__ = "High-performance REST API server";
Runtime Configuration
__port__ / __PORT__
Type: number
Default: 3000
Description: Primary server listening port. Both properties are synchronized.
// Setting either property updates both
__sys__.__port__ = 8080;
console.log(__sys__.__PORT__); // 8080
__sys__.__PORT__ = 9000;
console.log(__sys__.__port__); // 9000
__env__
Type: string
Default: "development"
Description: Current execution environment.
Common Values:
"development"- Local development"production"- Production deployment"staging"- Staging environment"test"- Testing environment
__sys__.__env__ = "production";
// Use helper methods for checks
if (__sys__.$isProduction()) {
// Production-specific logic
}
__root__
Type: string
Default: process.cwd()
Description: Absolute path to the project root directory.
console.log(`Project root: ${__sys__.__root__}`);
__app_urls__
Type: Record<string, string>
Default: {}
Description: Map of application-specific URLs.
__sys__.__app_urls__ = {
api: "https://api.example.com",
docs: "https://docs.example.com",
frontend: "https://app.example.com",
};
console.log(__sys__.__app_urls__.api);
Configuration Methods
$update(data: Record<string, any>): void
Merges a configuration object into the system state. Handles intelligent synchronization of related properties.
__sys__.$update({
__version__: "2.0.0",
__port__: 8080,
__env__: "production",
customKey: "customValue",
});
Behavior:
- Performs shallow merge of provided data
- Automatically synchronizes
__port__and__PORT__ - Preserves existing properties not specified in the update
$add(key: string, value: any): void
Dynamically adds a custom property to the system configuration.
__sys__.$add("databaseUrl", "postgresql://localhost:5432/mydb");
console.log(__sys__.databaseUrl); // "postgresql://localhost:5432/mydb"
Use Cases:
- Runtime configuration injection
- Plugin-specific settings
- Dynamic feature flags
$get<T>(key: string, defaultValue?: T): T
Safely retrieves a configuration value with an optional fallback.
const dbUrl = __sys__.$get(
"databaseUrl",
"postgresql://localhost:5432/default"
);
const timeout = __sys__.$get<number>("requestTimeout", 30000);
Type Safety:
// Generic type parameter ensures type safety
const port: number = __sys__.$get<number>("__port__", 3000);
$has(key: string): boolean
Checks if a configuration key exists.
if (__sys__.$has("databaseUrl")) {
// Database configuration is available
}
$remove(key: string): boolean
Removes a custom property from the configuration.
const removed = __sys__.$remove("temporaryFlag");
console.log(removed); // true if property existed, false otherwise
Note: Cannot remove core system properties (__version__, __port__, etc.).
$keys(): string[]
Returns an array of all configuration keys, excluding internal methods and API properties.
const keys = __sys__.$keys();
console.log(keys); // ["__version__", "__name__", "__port__", "customKey", ...]
Filtering:
- Excludes properties starting with
$(methods) - Excludes
__ENV__manager - Excludes internal API references
$toJSON(): Record<string, any>
Serializes the configuration to a plain JSON object.
const config = __sys__.$toJSON();
console.log(JSON.stringify(config, null, 2));
Output Example:
{
"__version__": "1.0.0",
"__name__": "my-app",
"__port__": 8080,
"__env__": "production",
"customKey": "value"
}
$reset(): void
Resets all configuration to default values.
__sys__.$reset();
console.log(__sys__.__version__); // "0.0.0"
console.log(__sys__.__port__); // 3000
Warning: This operation is destructive and cannot be undone. Use with caution.
$clone(): XyPrissSys
Creates a deep independent copy of the current configuration.
const backup = __sys__.$clone();
// Modify current config
__sys__.__port__ = 9000;
// Backup remains unchanged
console.log(backup.__port__); // Original value
Environment Helper Methods
$isProduction(): boolean
Returns true if __env__ is "production".
if (__sys__.$isProduction()) {
// Enable production optimizations
}
$isDevelopment(): boolean
Returns true if __env__ is "development".
if (__sys__.$isDevelopment()) {
// Enable debug logging
}
$isStaging(): boolean
Returns true if __env__ is "staging".
if (__sys__.$isStaging()) {
// Use staging database
}
$isTest(): boolean
Returns true if __env__ is "test".
if (__sys__.$isTest()) {
// Use test fixtures
}
$isEnvironment(envName: string): boolean
Checks if __env__ matches a custom environment name.
if (__sys__.$isEnvironment("qa")) {
// QA-specific configuration
}
Best Practices
1. Initialize Early
Set configuration values as early as possible in your application lifecycle:
import { createServer } from "xypriss";
// Configure before server creation
__sys__.$update({
__version__: "1.0.0",
__name__: "my-api",
__env__: process.env.NODE_ENV || "development",
});
const app = createServer({
server: { port: __sys__.__port__ },
});
2. Use Type-Safe Getters
Always use $get<T>() with explicit types for custom configuration:
const maxConnections = __sys__.$get<number>("maxConnections", 100);
const apiKey = __sys__.$get<string>("apiKey");
3. Validate Critical Configuration
Check for required configuration at startup:
const requiredKeys = ["databaseUrl", "apiKey", "secretKey"];
for (const key of requiredKeys) {
if (!__sys__.$has(key)) {
throw new Error(`Missing required configuration: ${key}`);
}
}
4. Avoid Runtime Mutations in Production
Configuration should be set during initialization. Avoid modifying configuration at runtime in production:
// Good: Set during initialization
__sys__.$update({ maxRetries: 3 });
// Avoid: Runtime modification
if (someCondition) {
__sys__.__port__ = 9000; // Risky in production
}
5. Document Custom Properties
When adding custom configuration, document the expected structure:
interface CustomConfig {
databaseUrl: string;
redisHost: string;
maxConnections: number;
}
__sys__.$update({
databaseUrl: "postgresql://...",
redisHost: "localhost",
maxConnections: 100,
} as CustomConfig);
Integration with __cfg__
The __sys__ configuration is separate from the __cfg__ server configuration manager. Use __sys__ for application-level metadata and __cfg__ for server-specific settings.
// Application metadata (use __sys__)
__sys__.__version__ = "1.0.0";
// Server configuration (use __cfg__)
__cfg__.update("server", { port: 8080 });
Thread Safety
The configuration system is not thread-safe. Avoid concurrent modifications from multiple execution contexts.
Serialization
Configuration can be serialized for logging or debugging:
import fs from "fs";
// Export configuration
const config = __sys__.$toJSON();
fs.writeFileSync("config.json", JSON.stringify(config, null, 2));
// Import configuration
const savedConfig = JSON.parse(fs.readFileSync("config.json", "utf-8"));
__sys__.$update(savedConfig);
Related Documentation
Version: XyPriss v6.0.0+
Last Updated: 2026-01-12