3.0.4

changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2025-08-29 - 3.0.4 - fix(smartsystem)
+Bump version to 3.0.4
+
+- Patch release: increment package version to 3.0.4
+- No functional code changes detected in source files
+- Tests are present but contain placeholder implementations
+- Dependencies are pinned as wildcard '*' and were not updated
+
+## 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)
 Normalize package scopes, update dev dependencies and tooling, add pnpm workspace and packageManager, remove GitLab CI, and update imports/docs/tests
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@push.rocks/smartsystem",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@push.rocks/smartsystem",
-      "version": "3.0.2",
+      "version": "3.0.4",
       "license": "MIT",
       "dependencies": {
         "@push.rocks/lik": "^6.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartsystem",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "A TypeScript library for interacting with the system it's running on, including environment, network, and hardware information.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",

readme.md

@@ -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
-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
 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
 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
-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
-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
-(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
-(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
-(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 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
 

ts/00_commitinfo_data.ts

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