Runtime Environment

XyPriss Global Runtime APIs

Centralized, type-safe, and secure access to system variables, configurations, and immutable constants across the entire application lifecycle.

XyPriss introduces three primary global namespaces to the execution environment. These namespaces are injected into the globalThis context, making them accessible from any module without requiring explicit local imports, provided the framework has been initialized.

sys

Manages system-level metadata, environment variables, hardware telemetry, and high-performance filesystem operations.

cfg

Acts as the single source of truth for server and plugin configurations with automated state propagation.

const

Enforces strict data integrity through a global constants registry and recursive deep immutability proxies.

sys: System Runtime Environment

The __sys__ object provides structured access to the application's runtime metadata and environment-specific utilities.

Core Properties

Property	Description
__version__	The current semantic version of the application.
__name__	The unique identifier for the application instance.
__env__	The current execution environment (e.g., "development", "production").
__port__ / __PORT__	Synchronized access to the primary server port.

Environment Management

The __sys__.__env__ utility provides a type-safe wrapper around process.env:

typescript

// Retrieval with fallback
const apiKey = __sys__.__env__.get("API_KEY", "default_value");

// Existence verification
if (__sys__.__env__.has("DATABASE_URL")) {
    // Logic for database initialization
}

cfg: Centralized Configuration Management

The __cfg__ API is a singleton manager for the XyPriss Server Configuration (XPSC). It ensures that configuration updates are propagated correctly and that components always access the most recent state.

get(section)

Retrieves a specific configuration segment.

update(section, partialValue)

Performs a deep merge of the provided values into the existing configuration.

getAll()

Returns a snapshot of the entire configuration state.

Integration with Immutability

When the server is initialized via createServer, the configuration managed by __cfg__ is automatically transitioned into an immutable state using the __const__ engine. Subsequent attempts to modify the configuration via __cfg__.update() will throw a runtime exception.

const: Immutability Engine

The __const__ API is the primary mechanism for enforcing data integrity within XyPriss. It serves two distinct purposes: managing a registry of named constants and creating deeply immutable object structures.

Named Constants Registry

Use $set to register a value that must remain unchanged for the duration of the process.

typescript

__const__.$set("MAX_RETRIES", 5);

// Attempting to redefine will throw an error
__const__.$set("MAX_RETRIES", 10); // Error: Cannot redefine constant "MAX_RETRIES"

Deep Immutability with $make

The $make method transforms an object, array, Map, or Set into a deeply immutable structure using recursive Proxies and Object.freeze.

typescript

const secureConfig = __const__.$make({
    security: {
        level: "high",
        roles: ["admin", "user"],
    },
});

// Any attempt to modify nested properties will fail
secureConfig.security.level = "low"; // Error: Cannot modify immutable property
secureConfig.security.roles.push("guest"); // Error: Cannot modify immutable array

Deep Immutability Mechanics

It is critical to distinguish between variable reassignment and object property modification when working with the Immutability Engine.

Variable Reassignment

The __const__.$make() method returns an immutable Proxy. However, it cannot prevent the JavaScript engine from reassigning a variable declared with let.

typescript

let x = __const__.$make({ value: 10 });
x = 20; // Valid JS. Not intercepted.

Always use the const keyword to prevent reassignment.

Property Modification

The Immutability Engine intercepts operations that attempt to mutate the state of the object itself, including nested properties and arrays.

typescript

const x = __const__.$make({ value: 10 });
x.value = 20; // Throws Runtime Error.

Property assignments/deletions
Array mutations (push, pop, etc.)
Map/Set mutations (set, add, etc.)

Initialization and Availability

In Application Code

The global APIs are initialized automatically when any part of the XyPriss framework is imported.

typescript

import { createServer } from "xypriss";

// Globals are now available
console.log(__sys__.__version__);

In Independent Scripts

For scripts that do not initialize a full server instance, ensure the framework is loaded to register the globals.

typescript

import "xypriss"; // Side-effect import

const immutableData = __const__.$make({ key: "value" });

Runtime Verification

To verify if the globals are correctly registered, you can check their existence on globalThis.

typescript

if (typeof __const__ !== "undefined") {
    // Framework is initialized
}

Deep Dive: XHSC Engine

Learn about the high-performance Go core that powers the underlying system capabilities of __sys__.