smartnetwork/readme.hints.md

# Project Analysis

## Architecture Overview
This is a comprehensive network diagnostics toolkit that provides various network-related utilities. The main entry point is the `SmartNetwork` class which orchestrates all functionality.

Key features:
- Speed testing via Cloudflare (parallelizable with duration support)
- Ping operations with statistics
- Port availability checks (local and remote)
- Network gateway discovery
- Public IP retrieval
- DNS resolution
- HTTP endpoint health checks
- Traceroute functionality (with fallback stub)

## Key Components

### SmartNetwork Class
- Central orchestrator for all network operations
- Supports caching via `cacheTtl` option for gateway and public IP lookups
- Plugin architecture for extensibility

### CloudflareSpeed Class
- Handles internet speed testing using Cloudflare's infrastructure
- Supports parallel streams and customizable test duration
- Measures both download and upload speeds using progressive chunk sizes
- Includes latency measurements (jitter, median, average)

### Error Handling
- Custom `NetworkError` and `TimeoutError` classes for better error context
- Error codes follow Node.js conventions (ENOTSUP, EINVAL, ETIMEOUT)

### Logging
- Global logger interface for consistent logging across the codebase
- Replaceable logger implementation (defaults to console)
- Used primarily for error reporting in speed tests

### Statistics Helpers
- Utility functions for statistical calculations (average, median, quartile, jitter)
- Used extensively by speed testing and ping operations

## Recent Changes (v4.0.0 - v4.0.1)
- Added configurable speed test options (parallelStreams, duration)
- Introduced plugin architecture for runtime extensibility
- Enhanced error handling with custom error classes
- Added global logging interface
- Improved connection management by disabling HTTP connection pooling
- Fixed memory leaks from listener accumulation
- Minor formatting fixes for consistency

## Testing
- Comprehensive test suite covering all major features
- Tests run on both browser and node environments
- Uses @push.rocks/tapbundle for testing with expectAsync
- Performance tests for speed testing functionality
- Edge case handling for network errors and timeouts

## Technical Details
- ESM-only package (module type)
- TypeScript with strict typing
- Depends on external modules for specific functionality:
  - @push.rocks/smartping for ICMP operations
  - public-ip for external IP discovery
  - systeminformation for network interface details
  - isopen for remote port checking
- Uses native Node.js modules for DNS, HTTP/HTTPS, and network operations

## Design Patterns
- Factory pattern for plugin registration
- Caching pattern with TTL for expensive operations
- Promise-based async/await throughout
- Deferred promises for complex async coordination
- Error propagation with custom error types
fix(tests): Update dev dependencies and refactor test assertions for improved clarity 2025-05-19 09:15:42 +00:00			`# Project Analysis`

			`## Architecture Overview`
			This is a comprehensive network diagnostics toolkit that provides various network-related utilities. The main entry point is the `SmartNetwork` class which orchestrates all functionality.

			`Key features:`
			`- Speed testing via Cloudflare (parallelizable with duration support)`
			`- Ping operations with statistics`
			`- Port availability checks (local and remote)`
			`- Network gateway discovery`
			`- Public IP retrieval`
			`- DNS resolution`
			`- HTTP endpoint health checks`
			`- Traceroute functionality (with fallback stub)`

			`## Key Components`

			`### SmartNetwork Class`
			`- Central orchestrator for all network operations`
			- Supports caching via `cacheTtl` option for gateway and public IP lookups
			`- Plugin architecture for extensibility`

			`### CloudflareSpeed Class`
			`- Handles internet speed testing using Cloudflare's infrastructure`
			`- Supports parallel streams and customizable test duration`
			`- Measures both download and upload speeds using progressive chunk sizes`
			`- Includes latency measurements (jitter, median, average)`

			`### Error Handling`
			- Custom `NetworkError` and `TimeoutError` classes for better error context
			`- Error codes follow Node.js conventions (ENOTSUP, EINVAL, ETIMEOUT)`

			`### Logging`
			`- Global logger interface for consistent logging across the codebase`
			`- Replaceable logger implementation (defaults to console)`
			`- Used primarily for error reporting in speed tests`

			`### Statistics Helpers`
			`- Utility functions for statistical calculations (average, median, quartile, jitter)`
			`- Used extensively by speed testing and ping operations`

			`## Recent Changes (v4.0.0 - v4.0.1)`
			`- Added configurable speed test options (parallelStreams, duration)`
			`- Introduced plugin architecture for runtime extensibility`
			`- Enhanced error handling with custom error classes`
			`- Added global logging interface`
			`- Improved connection management by disabling HTTP connection pooling`
			`- Fixed memory leaks from listener accumulation`
			`- Minor formatting fixes for consistency`

			`## Testing`
			`- Comprehensive test suite covering all major features`
			`- Tests run on both browser and node environments`
			`- Uses @push.rocks/tapbundle for testing with expectAsync`
			`- Performance tests for speed testing functionality`
			`- Edge case handling for network errors and timeouts`

			`## Technical Details`
			`- ESM-only package (module type)`
			`- TypeScript with strict typing`
			`- Depends on external modules for specific functionality:`
			`- @push.rocks/smartping for ICMP operations`
			`- public-ip for external IP discovery`
			`- systeminformation for network interface details`
			`- isopen for remote port checking`
			`- Uses native Node.js modules for DNS, HTTP/HTTPS, and network operations`

			`## Design Patterns`
			`- Factory pattern for plugin registration`
			`- Caching pattern with TTL for expensive operations`
			`- Promise-based async/await throughout`
			`- Deferred promises for complex async coordination`
			`- Error propagation with custom error types`