@bernierllc/neverhub-adapter

Standardized adapter for integrating BernierLLC packages with NeverHub service discovery and event bus system.

Installation

``bash
npm install @bernierllc/neverhub-adapter
`

Features

- Auto-Detection: Automatically detects if NeverHub is available in the environment
- Service Registration: Register package capabilities and dependencies with service discovery
- Event System: Publish/subscribe to events across packages in the ecosystem
- Service Discovery: Find and use other packages dynamically
- Health Monitoring: Report package health status and metrics
- Configuration: Load configuration and connection strings from NeverHub
- Graceful Degradation: Full functionality when NeverHub is unavailable

Quick Start

$3

`typescript
import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';

export class MyPackage {
private neverhub?: NeverHubAdapter;

async initialize(): Promise {
// Auto-detect NeverHub
if (await NeverHubAdapter.detect()) {
this.neverhub = new NeverHubAdapter();

// Register with NeverHub
await this.neverhub.register({
type: 'my-package',
name: '@bernierllc/my-package',
version: '1.0.0',
capabilities: [
{ type: 'data', name: 'processing', version: '1.0.0' }
],
dependencies: ['logging']
});
}

await this.initializeCore();
}
}
`

$3

`typescript
// Safe event publishing - works even when NeverHub is unavailable
await this.neverhub?.publishEvent({
type: 'data.processed',
data: { recordId: '123', status: 'success' },
source: 'my-package'
});
`

$3

`typescript
// Subscribe to events with pattern matching
const unsubscribe = await this.neverhub?.subscribe('user.*', async (event) => {
console.log('User event received:', event);
});

// Clean up subscription when done
// unsubscribe?.();
`

$3

`typescript
// Find services by capability
const services = await this.neverhub?.discover({
capabilityTypes: ['logging']
});

if (services?.available.includes('structured-logging')) {
const logger = await this.neverhub.getService('structured-logging');
// Use the logger service
}
`

$3

`typescript
// Load configuration with defaults
const config = await this.neverhub?.getConfiguration('my-package', {
logging: { level: 'info' },
retries: 3
});

// Get connection strings
const dbConnection = await this.neverhub?.getConnectionString('my-package', 'database');
`

$3

`typescript
// Register health check
await this.neverhub?.registerHealthCheck('my-package', async () => {
return {
healthy: this.isOperational(),
message: 'Service is running normally',
metadata: { uptime: process.uptime() }
};
});

// Report metrics
await this.neverhub?.reportMetric('my-package', {
name: 'requests_total',
value: 100,
type: MetricType.COUNTER,
labels: { status: 'success' }
});
`

API Reference

$3

#### Static Methods

- static detect(): Promise - Detect if NeverHub is available

#### Instance Methods

##### Core Methods
- initialize(): Promise - Initialize the adapter
- register(registration: PackageRegistration): Promise - Register package
- getState(): AdapterState - Get current adapter state
- isAvailable(): boolean - Check if NeverHub is available
- isInitialized(): boolean - Check if adapter is initialized
- isRegistered(): boolean - Check if package is registered

##### Event Methods
- publishEvent(event: Event): Promise - Publish event
- subscribe(pattern: string, handler: EventHandler): Promise<() => void> - Subscribe to events

##### Discovery Methods
- discover(criteria: DiscoveryCriteria): Promise - Discover services
- getService(serviceName: string): Promise - Get specific service

##### Configuration Methods
- getConfiguration(packageName: string, defaults?: any): Promise - Get configuration
- getConnectionString(packageName: string, connectionName: string): Promise - Get connection string
- getEnvironmentConfiguration(packageName: string, environment: string, defaults?: any): Promise - Get environment-specific configuration

##### Health Methods
- registerHealthCheck(packageName: string, checkFn: HealthCheckFunction): Promise - Register health check
- reportMetric(packageName: string, metric: Metric): Promise - Report metric

$3

The adapter can be configured with environment variables:

- NEVERHUB_API_URL - Custom NeverHub API URL
- NEVERHUB_ENDPOINT - Alternative endpoint specification
- NEVERHUB_HOST - Host-only specification (protocol will be added)

Or programmatically:

`typescript
const adapter = new NeverHubAdapter({
apiUrl: 'http://custom.neverhub.com:3001',
timeout: 5000,
maxRetries: 5,
debug: true
});
`

$3

#### PackageRegistration
`typescript
interface PackageRegistration {
type: string; // Package type identifier
name: string; // Full package name including scope
version: string; // Semantic version
dependencies: string[]; // List of dependency package names
capabilities: Capability[]; // List of capabilities provided
discoveryEnabled?: boolean; // Whether discoverable by others
discoverySubscriptions?: DiscoverySubscription[];
webhookUrl?: string; // Optional webhook URL
}
`

#### Event
`typescript
interface Event {
type: string; // Event type identifier
data: any; // Event payload
source?: string; // Source package identifier
timestamp?: string; // Event timestamp (ISO string)
metadata?: Record; // Additional metadata
}
`

#### Capability
`typescript
interface Capability {
type: string; // Capability type (e.g., 'data', 'logging')
name: string; // Specific capability name
version: string; // Version of the capability interface
metadata?: Record; // Additional metadata
}
`

Environment Detection

The adapter automatically detects NeverHub availability through:

1. Environment Variables: Checks for NEVERHUB_API_URL, NEVERHUB_ENDPOINT, or NEVERHUB_HOST
2. Default Endpoints: Tests http://localhost:3001 and http://neverhub:3001
3. Health Check: Validates API availability at /api/health

Graceful Degradation

When NeverHub is not available, the adapter:
- Returns default values for configuration requests
- Silently ignores event publishing attempts
- Returns empty results for service discovery
- Logs warnings for debugging but never throws errors
- Maintains full package functionality

Error Handling

The adapter is designed with graceful degradation as a core principle:

- Never throws errors due to NeverHub unavailability
- Logs warnings for debugging when operations fail
- Returns sensible defaults when NeverHub data is unavailable
- Maintains package functionality regardless of NeverHub state

Advanced Usage

$3

`typescript
const adapter = new NeverHubAdapter({
apiUrl: 'http://my-neverhub.internal:3001',
timeout: 10000,
maxRetries: 5,
debug: process.env.NODE_ENV === 'development'
});
`

$3

`typescript
const config = await adapter.getEnvironmentConfiguration(
'my-package',
process.env.NODE_ENV || 'development',
{ logging: { level: 'info' } }
);
`

$3

The event system supports flexible pattern matching:

- * - Matches any event type
- user.* - Matches all user-related events
- service.*.created - Matches creation events from any service
- exact.match - Matches only the exact event type

$3

For advanced use cases, utility functions are exported:

`typescript
import {
detectNeverHub,
publishEvent,
discoverServices,
validatePackageRegistration
} from '@bernierllc/neverhub-adapter';
``

See Also

This package integrates with other BernierLLC packages:
- @bernierllc/retry-policy - Used internally for retry logic
- @bernierllc/logging-core - Can be discovered via service discovery

License

Copyright (c) 2025 Bernier LLC. All rights reserved.