XyPriss API Documentation

Version Compatibility: XyPriss v6.0.0 and above

Overview

Welcome to the comprehensive XyPriss API documentation. This documentation covers all APIs available in the XyPriss framework, organized by functional area.

Documentation Structure

System API (__sys__)

The System API provides comprehensive access to system resources, file operations, and runtime configuration.

Main Documentation:

• System API Overview - Introduction and architecture
• Complete Reference - All methods at a glance

Configuration & Environment:

• Configuration Management - Application metadata and settings
• Environment Variables - Environment variable management

System Monitoring:

• CPU Monitoring - CPU usage and core information
• Memory Management - RAM and swap statistics
• Network Statistics - Network interfaces and bandwidth
• Process Management - Process information and monitoring
• Disk Information - Storage and filesystem details

Migration:

• Migration Guide v5→v6 - Upgrading from XyPriss v5

Global APIs

Additional global APIs available in XyPriss:

• __cfg__ - Server configuration management
• __const__ - Immutability engine and constants registry

See Global APIs Documentation for details.

Quick Start

Installation

xfpm i xypriss@^6.0.0
# or
bun add xypriss@^6.0.0

Basic Usage

import { createServer } from "xypriss";

// System API is available globally as __sys__
console.log(__sys__.__version__);

// Get system information
const info = __sys__.$info();
const cpu = __sys__.$cpu();
const memory = __sys__.$memory();

// File operations
const files = __sys__.$ls("./src");
const content = __sys__.$read("config.json");

// Create server
const app = createServer({
  server: { port: __sys__.__port__ },
});

API Categories

1. Configuration & Metadata

Manage application configuration, version information, and runtime metadata.

Key Methods:

• $update() - Merge configuration
• $get() - Retrieve values
• $isProduction() - Environment checks

Documentation: Configuration Management

2. System Monitoring

Real-time access to hardware metrics and system health.

Key Methods:

• $info() - System information
• $cpu() - CPU statistics
• $memory() - Memory usage
• $network() - Network statistics

Documentation:

• CPU Monitoring
• Memory Management
• Network Statistics

3. Process Management

Monitor and analyze running processes.

Key Methods:

• $processes() - List processes
• $processes({ topCpu: N }) - Top CPU consumers
• $processes({ topMem: N }) - Top memory consumers

Documentation: Process Management

4. File System Operations

Comprehensive file and directory manipulation.

Key Methods:

• $read(), $write() - File I/O
• $ls(), $mkdir() - Directory operations
• $find(), $grep() - Search operations

Documentation: Complete Reference

5. Storage & Disk

Monitor disk usage and storage capacity.

Key Methods:

• $disks() - Disk information
• $du() - Directory usage

Documentation: Disk Information

Type Definitions

All types are fully documented and exported:

import type {
  SystemInfo,
  CpuUsage,
  CpuInfo,
  MemoryInfo,
  DiskInfo,
  NetworkStats,
  NetworkInterface,
  ProcessInfo,
  FileStats,
  SearchMatch,
} from "xypriss";

Common Use Cases

1. Health Monitoring

function checkSystemHealth() {
  const cpu = __sys__.$cpu();
  const memory = __sys__.$memory();
  const disks = __sys__.$disks();

  return {
    cpu: cpu.overall < 80,
    memory: memory.usage_percent < 85,
    disk: disks.every((d) => d.usage_percent < 90),
  };
}

2. Resource Management

function optimizeResources() {
  const memory = __sys__.$memory();

  if (memory.usage_percent > 85) {
    // Trigger garbage collection
    global.gc?.();

    // Clear caches
    cache.clear();
  }
}

3. Configuration Loading

function loadConfig() {
  return {
    port: parseInt(__sys__.__ENV__.get("PORT", "3000")),
    env: __sys__.__env__,
    dbUrl: __sys__.__ENV__.get("DATABASE_URL"),
    apiKey: __sys__.__ENV__.get("API_KEY"),
  };
}

4. File Processing

function processLogs() {
  const logFiles = __sys__.$findByExt("logs", "log");

  logFiles.forEach((file) => {
    const lines = __sys__.$readNonEmptyLines(file);
    const errors = lines.filter((l) => l.includes("ERROR"));

    if (errors.length > 0) {
      console.log(`${file}: ${errors.length} errors`);
    }
  });
}

Performance Guidelines

1. Synchronous Operations

All System API methods are synchronous and block the event loop:

// This blocks until complete
const files = __sys__.$lsRecursive("large-directory");

// For large operations, consider worker threads

2. Caching

Cache frequently accessed data:

// Cache system info (rarely changes)
const systemInfo = __sys__.$info();

// Cache file lists (update periodically)
let fileCache: string[] = [];
setInterval(() => {
  fileCache = __sys__.$ls("src");
}, 60000);

3. Polling Frequency

Avoid excessive polling:

// Good: Poll every 5-10 seconds
setInterval(() => {
  const cpu = __sys__.$cpu();
  if (cpu.overall > 80) console.warn("High CPU");
}, 5000);

// Avoid: Polling too frequently
setInterval(() => __sys__.$cpu(), 100); // Too frequent!

Error Handling

All methods may throw XyPrissError:

import { XyPrissError } from "xypriss";

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

Platform Support

Migration

Upgrading from XyPriss v5? See the Migration Guide.

Additional Resources

• GitHub Repository
• Issue Tracker
• Global APIs

Contributing

Documentation improvements are welcome! Please submit pull requests to the GitHub repository.

Documentation Version: 1.0.0
XyPriss Version: v6.0.0+
Last Updated: 2026-01-12