push.rocks/smartsystem
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

fix(readme): Update README: expand documentation, add installation, usage examples, API overview, and advanced guides

Browse Source
This commit is contained in:
Jürgen Kunz
2025-08-29 12:59:57 +00:00
parent 71f44f64fb
commit 71422beea3
3 changed files with 199 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
changelog.md
View File

@@ -1,5 +1,15 @@
# Changelog # Changelog
## 2025-08-29 - 3.0.3 - fix(readme)
Update README: expand documentation, add installation, usage examples, API overview, and advanced guides
- Completely revamped README with a clearer project description and features list
- Added Installation section with npm / pnpm / yarn examples
- Added Quick Start, API overview, and multiple usage examples (env, CPU, network, systeminformation)
- Added Real-World Use Cases (health check, network monitoring, resource scaling) and Advanced Features (cross-platform, Docker detection)
- Clarified TypeScript support and added links to full API documentation
- Documentation-only changes; no code or API behaviour modified
## 2025-08-29 - 3.0.2 - fix(smartsystem) ## 2025-08-29 - 3.0.2 - fix(smartsystem)
Normalize package scopes, update dev dependencies and tooling, add pnpm workspace and packageManager, remove GitLab CI, and update imports/docs/tests Normalize package scopes, update dev dependencies and tooling, add pnpm workspace and packageManager, remove GitLab CI, and update imports/docs/tests

270
readme.md
View File

@@ -1,131 +1,237 @@
# @push.rocks/smartsystem # @push.rocks/smartsystem 🚀
Interact with the system your Node.js app runs on. **Smart System Interaction for Node.js**
## Features > Zero-hassle system information and environment management for modern Node.js applications.
- Simple class: expose system info through a single `Smartsystem` instance ## 🌟 Features
- Env access: read and manage env vars via `@push.rocks/smartenv`
- CPU info: get `os.cpus()` without importing `os`
- Network utilities: high-level helpers from `@push.rocks/smartnetwork`
- Deep stats: tap into `systeminformation` for OS, hardware, and load data
- TypeScript-first: typed API, works great from TS and JS
## Install `@push.rocks/smartsystem` consolidates system interaction into a single, elegant TypeScript-first API:
To incorporate @push.rocks/smartsystem into your project, you'll need to install the package via npm. You can do this by running the following command in your project's root directory: - 🔧 **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 ```bash
npm install @push.rocks/smartsystem --save # Using npm
npm install @push.rocks/smartsystem
# Using pnpm (recommended)
pnpm add @push.rocks/smartsystem
# Using yarn
yarn add @push.rocks/smartsystem
``` ```
This command will download @push.rocks/smartsystem and add it to your project's `package.json` file as a dependency. ## 🚀 Quick Start
## Usage
The `@push.rocks/smartsystem` module offers a convenient way to interact with the system your application is running on. Below are detailed examples that demonstrate how to utilize its full potential. These examples are written in TypeScript and showcase different cases and features of the module.
### Getting Started
First, ensure that you are importing the module correctly in your TypeScript file:
```typescript ```typescript
import { Smartsystem } from '@push.rocks/smartsystem'; import { Smartsystem } from '@push.rocks/smartsystem';
// Create your system interface
const mySystem = new Smartsystem();
// You're ready to rock! 🎸
``` ```
### Creating an Instance of Smartsystem ## 📖 API Overview
To use the functionalities provided by `@push.rocks/smartsystem`, you need to create a new instance of the `Smartsystem` class. 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 ```typescript
const mySystem = new Smartsystem(); 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');
``` ```
## API Overview ### CPU Information at Your Fingertips
- `Smartsystem.env`: instance of `Smartenv` from `@push.rocks/smartenv`
Useful for reading and validating environment variables.
- `Smartsystem.cpus`: result of `os.cpus()`
Array of CPU core descriptions from Node’s built‑in `os` module.
- `Smartsystem.network`: instance of `SmartNetwork` from `@push.rocks/smartnetwork`
Inspect interfaces, addresses, and network details.
- `Smartsystem.information`: re-export of `systeminformation`
Call any method, e.g. `osInfo()`, `system()`, `currentLoad()`, `networkStats()`.
### Accessing Environment Variables
`@push.rocks/smartsystem` integrates with `@push.rocks/smartenv` to provide an easy way to handle environment variables.
```typescript ```typescript
console.log(mySystem.env.getEnvVars()); const mySystem = new Smartsystem();
// Get CPU details
console.log(`Running on ${mySystem.cpus.length} CPU cores`);
console.log(`Primary CPU: ${mySystem.cpus[0].model}`);
``` ```
### Getting CPU Information ### Network Intelligence
You can retrieve information about the CPUs of the system:
```typescript ```typescript
console.log(mySystem.cpus[0]); // Logs details about the first CPU const mySystem = new Smartsystem();
// Get comprehensive network information
const networkInfo = await mySystem.network.getNetworkInfo();
console.log('Network interfaces:', networkInfo);
``` ```
### Working with Network Interfaces ### Deep System Insights
The module allows you to work with network interfaces, making use of `@push.rocks/smartnetwork`: Access detailed system information for advanced use cases:
```typescript ```typescript
(async () => { const mySystem = new Smartsystem();
console.log(await mySystem.network.getNetworkInfo());
})(); // 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`);
``` ```
### System Information ## 🎯 Real-World Use Cases
For more detailed system information such as hardware specs or software versions, `@push.rocks/smartsystem` relies on the `systeminformation` library: ### System Health Monitoring
Create a simple health check for your application:
```typescript ```typescript
(async () => { const mySystem = new Smartsystem();
console.log(await mySystem.information.system());
// Output detailed information about the system like manufacturer, model, etc.
console.log(await mySystem.information.osInfo()); async function healthCheck() {
// Output detailed information about the operating system 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)}%`
}))
}
};
}
``` ```
### Real-World Scenarios ### Network Traffic Analysis
Now that we've covered the basics let's dive into some real-world applications: Monitor network activity for debugging or performance optimization:
#### Monitoring System Load
You can monitor the current load on the system to make decisions or trigger actions when the system is under heavy use:
```typescript ```typescript
(async () => { const mySystem = new Smartsystem();
const systemLoad = await mySystem.information.currentLoad();
if (systemLoad.currentLoad > 80) {
console.log("High system load detected. Consider scaling or optimizing your applications.");
}
})();
```
#### Network Monitoring async function monitorNetwork() {
It's often useful to keep an eye on network interfaces, especially when diagnosing connectivity issues or monitoring network traffic:
```typescript
(async () => {
const defaultInterface = await mySystem.information.networkInterfaceDefault(); const defaultInterface = await mySystem.information.networkInterfaceDefault();
const interfaceStats = await mySystem.information.networkStats(defaultInterface); const baseline = await mySystem.information.networkStats(defaultInterface);
console.log(interfaceStats);
// Use this information to alert on unusual traffic patterns or drops in speed. // 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`);
}
``` ```
### Conclusion ### Smart Resource Scaling
`@push.rocks/smartsystem` offers a comprehensive toolkit for interacting with the underlying system your Node.js application runs on. From retrieving environment variables and CPU information to monitoring network interfaces and system load, this module provides everything you need to ensure your application can intelligently respond to its operating environment. Make intelligent decisions based on system resources:
Remember, the examples above only scratch the surface of what's possible with `@push.rocks/smartsystem`. For more detailed documentation on all available methods and their capabilities, refer to the [official documentation](https://pushrocks.gitlab.io/smartsystem/). ```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 ## License and Legal Information
@@ -144,4 +250,4 @@ 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. 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. 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.

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@push.rocks/smartsystem', name: '@push.rocks/smartsystem',
version: '3.0.2', version: '3.0.3',
description: 'A TypeScript library for interacting with the system it's running on, including environment, network, and hardware information.' description: 'A TypeScript library for interacting with the system it's running on, including environment, network, and hardware information.'
} }