smartsystem/readme.md

# @push.rocks/smartsystem 🚀
**Smart System Interaction for Node.js**

> Zero-hassle system information and environment management for modern Node.js applications.

## 🌟 Features

`@push.rocks/smartsystem` consolidates system interaction into a single, elegant TypeScript-first API:

- 🔧 **Unified System Interface** - One `Smartsystem` instance to rule them all
- 🌍 **Environment Management** - Smart env variable handling via [@push.rocks/smartenv](https://www.npmjs.com/package/@push.rocks/smartenv)
- 💻 **CPU Information** - Direct access to CPU specs without the boilerplate
- 🌐 **Network Intelligence** - Advanced networking utilities from [@push.rocks/smartnetwork](https://www.npmjs.com/package/@push.rocks/smartnetwork)
- 📊 **Deep System Insights** - Comprehensive hardware and OS data via [systeminformation](https://www.npmjs.com/package/systeminformation)
- ⚡ **TypeScript Native** - Built with TypeScript, for TypeScript (but works great with JS too!)

## 📦 Installation

Get started with your package manager of choice:

```bash
# Using npm
npm install @push.rocks/smartsystem

# Using pnpm (recommended)
pnpm add @push.rocks/smartsystem

# Using yarn
yarn add @push.rocks/smartsystem
```

## 🚀 Quick Start

```typescript
import { Smartsystem } from '@push.rocks/smartsystem';

// Create your system interface
const mySystem = new Smartsystem();

// You're ready to rock! 🎸
```

## 📖 API Overview

The `Smartsystem` class provides these powerful properties:

| Property | Type | Description |
|----------|------|-------------|
| `env` | `Smartenv` | Environment variable management with validation and type safety |
| `cpus` | `os.CpuInfo[]` | Direct access to CPU core information |
| `network` | `SmartNetwork` | Network interface inspection and utilities |
| `information` | `systeminformation` | Full access to the systeminformation library |

## 💡 Usage Examples

### Environment Variables Made Easy

```typescript
const mySystem = new Smartsystem();

// Get all environment variables
const envVars = mySystem.env.getEnvVars();

// Access specific variables with type safety
const apiKey = mySystem.env.getEnvVarOnDemand('API_KEY');
```

### CPU Information at Your Fingertips

```typescript
const mySystem = new Smartsystem();

// Get CPU details
console.log(`Running on ${mySystem.cpus.length} CPU cores`);
console.log(`Primary CPU: ${mySystem.cpus[0].model}`);
```

### Network Intelligence

```typescript
const mySystem = new Smartsystem();

// Get comprehensive network information
const networkInfo = await mySystem.network.getNetworkInfo();
console.log('Network interfaces:', networkInfo);
```

### Deep System Insights

Access detailed system information for advanced use cases:

```typescript
const mySystem = new Smartsystem();

// Hardware information
const systemInfo = await mySystem.information.system();
console.log(`System: ${systemInfo.manufacturer} ${systemInfo.model}`);

// Operating system details
const osInfo = await mySystem.information.osInfo();
console.log(`OS: ${osInfo.distro} ${osInfo.release}`);

// Real-time system metrics
const load = await mySystem.information.currentLoad();
console.log(`CPU Load: ${load.currentLoad.toFixed(2)}%`);

// Memory usage
const mem = await mySystem.information.mem();
console.log(`Memory: ${(mem.used / mem.total * 100).toFixed(2)}% used`);
```

## 🎯 Real-World Use Cases

### System Health Monitoring

Create a simple health check for your application:

```typescript
const mySystem = new Smartsystem();

async function healthCheck() {
  const load = await mySystem.information.currentLoad();
  const mem = await mySystem.information.mem();
  const disk = await mySystem.information.fsSize();
  
  return {
    status: 'healthy',
    metrics: {
      cpuLoad: `${load.currentLoad.toFixed(2)}%`,
      memoryUsage: `${(mem.used / mem.total * 100).toFixed(2)}%`,
      diskUsage: disk.map(fs => ({
        mount: fs.mount,
        usage: `${fs.use.toFixed(2)}%`
      }))
    }
  };
}
```

### Network Traffic Analysis

Monitor network activity for debugging or performance optimization:

```typescript
const mySystem = new Smartsystem();

async function monitorNetwork() {
  const defaultInterface = await mySystem.information.networkInterfaceDefault();
  const baseline = await mySystem.information.networkStats(defaultInterface);
  
  // Check again after 1 second
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  const current = await mySystem.information.networkStats(defaultInterface);
  const rxSpeed = (current[0].rx_sec / 1024 / 1024).toFixed(2);
  const txSpeed = (current[0].tx_sec / 1024 / 1024).toFixed(2);
  
  console.log(`📥 Download: ${rxSpeed} MB/s | 📤 Upload: ${txSpeed} MB/s`);
}
```

### Smart Resource Scaling

Make intelligent decisions based on system resources:

```typescript
const mySystem = new Smartsystem();

async function getOptimalWorkerCount() {
  const cpuCount = mySystem.cpus.length;
  const load = await mySystem.information.currentLoad();
  const mem = await mySystem.information.mem();
  
  // Scale workers based on available resources
  const memoryConstraint = Math.floor(mem.available / (512 * 1024 * 1024)); // 512MB per worker
  const cpuConstraint = Math.max(1, Math.floor(cpuCount * (1 - load.currentLoad / 100)));
  
  return Math.min(memoryConstraint, cpuConstraint, cpuCount);
}
```

## 🔧 Advanced Features

### Cross-Platform Compatibility

`@push.rocks/smartsystem` works seamlessly across different operating systems:

```typescript
const mySystem = new Smartsystem();

const osInfo = await mySystem.information.osInfo();
const platform = osInfo.platform; // 'linux', 'darwin', 'win32', etc.

// Platform-specific logic
if (platform === 'linux') {
  // Linux-specific operations
} else if (platform === 'darwin') {
  // macOS-specific operations
} else if (platform === 'win32') {
  // Windows-specific operations
}
```

### Docker & Container Detection

Detect if your application is running in a containerized environment:

```typescript
const mySystem = new Smartsystem();

const virt = await mySystem.information.dockerInfo();
if (virt.dockerContainers && virt.dockerContainers.length > 0) {
  console.log('🐳 Running in Docker');
}
```

## 🛠️ TypeScript Support

Full TypeScript support with comprehensive type definitions:

```typescript
import { Smartsystem } from '@push.rocks/smartsystem';
import type { Systeminformation } from 'systeminformation';

const mySystem = new Smartsystem();

// All methods are fully typed
const cpuInfo: Systeminformation.CpuData = await mySystem.information.cpu();
const memInfo: Systeminformation.MemData = await mySystem.information.mem();
```

## 📚 API Documentation

For complete API documentation, visit: [https://code.foss.global/push.rocks/smartsystem](https://code.foss.global/push.rocks/smartsystem)

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.