XyPriss System API Documentation

Version Compatibility: XyPriss v6.0.0 and above

Overview

The XyPriss System API (__sys__) represents a comprehensive, unified interface for interacting with the operating system, file system, and runtime environment. This API is designed to provide developers with a powerful, type-safe, and intuitive set of tools for building robust server applications.

Architecture

The System API follows a hierarchical inheritance structure that consolidates multiple specialized APIs into a single, flat interface:

XyPrissSys (Global Instance: __sys__)
    └── XyPrissFS (System Aggregator)
        └── SysApi (System Monitoring & Intelligence)
            └── FSApi (Filesystem Operations)
                └── PathApi (Path Manipulation)
                    └── BaseApi (Foundation Layer)

This architecture ensures that all capabilities are accessible directly from the __sys__ global instance without the need for nested property access.

Core Capabilities

The System API provides five primary categories of functionality:

1. System Configuration & Metadata

Management of application-level configuration, version information, and runtime metadata.

• Configuration Management
• Environment Variables
• Metadata Properties

2. System Monitoring & Intelligence

Real-time access to hardware metrics, process information, and system health data.

• CPU Monitoring
• Memory Management
• Disk Information
• Network Statistics
• Process Management
• Battery Status
• System Health

3. Filesystem Operations

Comprehensive file and directory manipulation with enhanced safety and convenience.

• Path Operations
• File I/O
• Directory Management
• File Metadata
• Search & Filter
• Advanced Operations

4. Search & Discovery

High-performance file and content search capabilities.

• File Search
• Content Grep
• Pattern Matching

5. Port & Network Utilities

Network interface inspection and port management.

• Port Scanning
• Network Interfaces

Global Access

The System API is available globally as __sys__ throughout your XyPriss application:

// No imports required - available globally
console.log(__sys__.__version__);
const cpuUsage = __sys__.$cpu();
const files = __sys__.$ls("./src");

Initialization

The __sys__ instance is automatically initialized when the XyPriss framework is loaded. For standalone scripts, ensure the framework is imported:

import "xypriss"; // Initializes global APIs

// __sys__ is now available

Type Safety

All System API methods are fully typed with TypeScript interfaces. Import types as needed:

import type { SystemInfo, CpuUsage, MemoryInfo } from "xypriss";

const info: SystemInfo = __sys__.$info();
const cpu: CpuUsage = __sys__.$cpu() as CpuUsage;

Error Handling

System API methods throw XyPrissError instances when operations fail. Always wrap potentially failing operations in try-catch blocks:

try {
    const content = __sys__.$read("config.json");
} catch (error) {
    if (error instanceof XyPrissError) {
        console.error(`Operation failed: ${error.message}`);
    }
}

Performance Considerations

The System API is built on a high-performance Rust binary (xsys) that executes operations natively. However, be mindful of:

• Synchronous Operations: Most methods are synchronous and block the event loop
• Large Directory Trees: Recursive operations on large directories may take time
• Frequent Polling: Avoid polling system metrics in tight loops

Platform Support

The System API supports the following platforms:

• Linux: Full support for all features
• macOS: Full support for all features
• Windows: Partial support (some Unix-specific features unavailable)

Platform-specific features are clearly marked in the documentation.

Security Considerations

• Path Traversal: All path operations are root-aware and prevent traversal outside the project directory
• Permissions: File operations respect system-level permissions
• Environment Variables: Use __sys__.__ENV__ for safe environment variable access

Migration from v5

If you are upgrading from XyPriss v5, please review the Migration Guide for breaking changes and new features.

Quick Reference

Most Common Operations

// System Information
const info = __sys__.$info();
const cpu = __sys__.$cpu();
const memory = __sys__.$memory();

// File Operations
const exists = __sys__.$exists("file.txt");
const content = __sys__.$read("file.txt");
__sys__.$write("output.txt", "data");

// Directory Operations
const files = __sys__.$ls("./src");
const allFiles = __sys__.$lsRecursive("./src");
__sys__.$mkdir("new-directory");

// Path Operations
const absolute = __sys__.$resolve("relative/path");
const joined = __sys__.$join("dir", "file.txt");

// Search Operations
const matches = __sys__.$find("src", ".*\\.ts$");
const grep = __sys__.$grep("src", "TODO");

// Environment
const nodeEnv = __sys__.__ENV__.get("NODE_ENV", "development");
const isProduction = __sys__.$isProduction();

API Reference Index

• Configuration Management
• Environment Variables
• CPU Monitoring
• Memory Management
• Disk Information
• Network Statistics
• Process Management
• Path Operations
• File I/O
• Directory Management
• Search & Filter

Support

For issues, questions, or feature requests, please refer to the XyPriss GitHub repository.

Note: This documentation covers features available in XyPriss v6.0.0 and above. Features may not be available in earlier versions.