XyPriss Immutability API (const)

The __const__ global API is the core engine for data integrity and state protection within the XyPriss framework. It provides a robust mechanism for defining global constants and creating deeply immutable data structures that are protected at the engine level via JavaScript Proxies.

Functional Components

The API is divided into two primary functional areas: the Named Constants Registry and the Deep Immutability Engine.

1. Named Constants Registry

The registry allows for the definition of key-value pairs that are locked upon creation. Unlike standard JavaScript variables, these constants cannot be redefined or deleted once set.

Methods

• $set(key, value): Registers a new constant. Throws an error if the key already exists.
• $get(key, defaultValue): Retrieves a constant value.
• $has(key): Returns a boolean indicating if a constant is registered.
• $keys(): Returns an array of all registered constant identifiers.

Example

__const__.$set("API_VERSION", "v2");

// This will throw an error
__const__.$set("API_VERSION", "v3");

2. Deep Immutability Engine ($make)

The $make method is a sophisticated utility that transforms standard JavaScript objects into immutable structures. It recursively applies protection to nested objects, arrays, Maps, and Sets.

Technical Implementation

• Object.freeze: Used for basic property protection.
• Proxies: Used to intercept and block mutation operations (set, delete, defineProperty) with descriptive error messages.
• WeakMap Caching: Ensures that circular references are handled correctly and that objects are not redundantly wrapped in multiple proxies, maintaining optimal performance.

Supported Data Types

• Objects: Protects all properties and prototype.
• Arrays: Blocks index assignment and mutation methods (push, pop, splice, etc.).
• Maps: Overrides set, delete, and clear.
• Sets: Overrides add, delete, and clear.

Usage Example

const securityPolicy = __const__.$make({
    firewall: {
        enabled: true,
        rules: ["ALLOW_HTTPS", "BLOCK_SSH"],
    },
});

// The following operations will throw runtime errors:
securityPolicy.firewall.enabled = false;
securityPolicy.firewall.rules.push("ALLOW_FTP");
delete securityPolicy.firewall;

Error Handling

When a modification attempt is intercepted, __const__ throws a detailed error indicating the exact path of the violation.

Example Error Message: [XyPrissConst] Cannot modify immutable property "Configs.server.port". Attempted to set value: 8080

Performance Considerations

While the Immutability Engine provides powerful protection, it should be used judiciously:

1. Initialization Cost: Creating a deep proxy for very large, deeply nested objects has a one-time CPU cost.
2. Memory: The WeakMap cache ensures memory efficiency by reusing proxies, but the proxies themselves occupy a small amount of additional memory.
3. Runtime: Accessing properties through a Proxy is slightly slower than direct access, though this is negligible for configuration and constant data.

Best Practices

• Configuration Locking: Use $make to lock configuration objects before passing them to untrusted modules or plugins.
• State Snapshots: When exporting internal state that should not be modified by the consumer, wrap the export in $make.
• Constants Naming: Use UPPER_SNAKE_CASE for keys in the constants registry to distinguish them from standard variables.