BREAKING CHANGE(smartnetwork): Enhance documentation and add configurable speed test options with plugin architecture improvements

readme.md

@@ -10,6 +10,17 @@ To install `@push.rocks/smartnetwork`, run the following command in your termina
 npm install @push.rocks/smartnetwork --save
 ```
 
+### Performing a Traceroute
+
+You can perform a hop-by-hop traceroute to measure latency per hop. Falls back to a single-hop stub if the `traceroute` binary is unavailable.
+
+```typescript
+const hops = await myNetwork.traceroute('google.com', { maxHops: 10, timeout: 5000 });
+hops.forEach(h =>
+  console.log(`${h.ttl}\t${h.ip}\t${h.rtt === null ? '*' : h.rtt + ' ms'}`),
+);
+```
+
 This command will download `@push.rocks/smartnetwork` and add it to your project's `package.json` file.
 
 ## Usage
@@ -32,14 +43,19 @@ const myNetwork = new SmartNetwork();
 
 ### Performing a Speed Test
 
-You can measure the network speed using the `getSpeed` method. This feature leverages Cloudflare's speed test capabilities to assess your internet connection's download and upload speeds.
+You can measure the network speed using the `getSpeed` method. It supports optional parameters:
+- `parallelStreams`: number of concurrent streams (default: 1)
+- `duration`: test duration in seconds (default: fixed segments)
 
 ```typescript
 const speedTest = async () => {
-  const speedResult = await myNetwork.getSpeed();
-  console.log(`Download speed: ${speedResult.downloadSpeed} Mbps`);
-  console.log(`Upload speed: ${speedResult.uploadSpeed} Mbps`);
-  console.log(`Latency: ${speedResult.averageTime} ms`);
+  // Default fixed-segment test
+  let r = await myNetwork.getSpeed();
+  console.log(`Download: ${r.downloadSpeed} Mbps, Upload: ${r.uploadSpeed} Mbps`);
+
+  // Parallel + duration-based test
+  r = await myNetwork.getSpeed({ parallelStreams: 3, duration: 5 });
+  console.log(`Download: ${r.downloadSpeed} Mbps, Upload: ${r.uploadSpeed} Mbps`);
 };
 
 speedTest();
@@ -64,71 +80,88 @@ checkLocalPort(8080); // Example port number
 
 ### Checking Remote Port Availability
 
-To verify if a certain port is available on a remote server, use `isRemotePortAvailable`. This can help determine if a service is up and reachable.
+To verify if a port is available on a remote server, use `isRemotePortAvailable`. You can specify target as `"host:port"` or host plus a numeric port.
 
 ```typescript
-const checkRemotePort = async (hostname: string, port: number) => {
-  const isAvailable = await myNetwork.isRemotePortAvailable(hostname, port);
-  if (isAvailable) {
-    console.log(`Port ${port} on ${hostname} is available.`);
-  } else {
-    console.log(`Port ${port} on ${hostname} is not available.`);
-  }
-};
+// Using "host:port"
+await myNetwork.isRemotePortAvailable('example.com:443');
 
-checkRemotePort('example.com', 443); // Checking HTTPS port on example.com
+// Using host + port
+await myNetwork.isRemotePortAvailable('example.com', 443);
+
+// UDP is not supported:
+try {
+  await myNetwork.isRemotePortAvailable('example.com', { port: 53, protocol: 'udp' });
+} catch (e) {
+  console.error((e as any).code); // ENOTSUP
+}
 ```
 
 ### Using Ping
 
-The `ping` method allows you to send ICMP packets to a host to measure round-trip time and determine if the host is reachable.
+The `ping` method sends ICMP echo requests and optionally repeats them to collect statistics.
 
 ```typescript
-const pingHost = async (hostname: string) => {
-  const pingResult = await myNetwork.ping(hostname);
-  if (pingResult.alive) {
-    console.log(`${hostname} is reachable. RTT: ${pingResult.time} ms`);
-  } else {
-    console.log(`${hostname} is not reachable.`);
-  }
-};
+// Single ping
+const p1 = await myNetwork.ping('google.com');
+console.log(`Alive: ${p1.alive}, RTT: ${p1.time} ms`);
 
-pingHost('google.com');
+// Multiple pings with statistics
+const stats = await myNetwork.ping('google.com', { count: 5 });
+console.log(
+  `min=${stats.min} ms, max=${stats.max} ms, avg=${stats.avg.toFixed(2)} ms, loss=${stats.packetLoss}%`,
+);
 ```
 
 ### Getting Network Gateways
 
-You can also retrieve information about your network gateways, including the default gateway used by your machine.
+You can also retrieve network interfaces (gateways) and determine the default gateway. Caching with TTL is supported via constructor options.
 
 ```typescript
-const showGateways = async () => {
-  const gateways = await myNetwork.getGateways();
-  console.log(gateways);
+// Create with cache TTL of 60 seconds
+const netCached = new SmartNetwork({ cacheTtl: 60000 });
 
-  const defaultGateway = await myNetwork.getDefaultGateway();
-  console.log(`Default Gateway: `, defaultGateway);
-};
+// List all interfaces
+const gateways = await netCached.getGateways();
+console.log(gateways);
 
-showGateways();
+// Get default gateway
+const defaultGw = await netCached.getDefaultGateway();
+console.log(defaultGw);
 ```
 
 ### Discovering Public IP Addresses
 
-To find out your public IPv4 and IPv6 addresses, the following method can be used:
+To find out your public IPv4 and IPv6 addresses (with caching):
 
 ```typescript
-const showPublicIps = async () => {
-  const publicIps = await myNetwork.getPublicIps();
-  console.log(`Public IPv4: ${publicIps.v4}`);
-  console.log(`Public IPv6: ${publicIps.v6}`);
-};
-
-showPublicIps();
+const publicIps = await netCached.getPublicIps();
+console.log(`Public IPv4: ${publicIps.v4}`);
+console.log(`Public IPv6: ${publicIps.v6}`);
 ```
 
 The `@push.rocks/smartnetwork` package provides an easy-to-use, comprehensive suite of tools for network diagnostics and monitoring, encapsulating complex network operations into simple asynchronous methods. By leveraging TypeScript, developers can benefit from type checking, ensuring that they can work with clear structures and expectations.
 
 These examples offer a glimpse into the module's utility in real-world scenarios, demonstrating its versatility in handling common network tasks. Whether you're developing a network-sensitive application, diagnosing connectivity issues, or simply curious about your network performance, `@push.rocks/smartnetwork` equips you with the tools you need.
+### Plugin Architecture
+
+You can extend `SmartNetwork` with custom plugins by registering them at runtime:
+
+```typescript
+import { SmartNetwork } from '@push.rocks/smartnetwork';
+
+// Define your plugin class or constructor
+class MyCustomPlugin {
+  // plugin implementation goes here
+}
+
+// Register and unregister your plugin by name
+SmartNetwork.registerPlugin('myPlugin', MyCustomPlugin);
+// Later, remove it if no longer needed
+SmartNetwork.unregisterPlugin('myPlugin');
+```
+
+Plugins enable you to dynamically augment the core functionality without altering the library's source.
 
 ## License and Legal Information