rn-network-quality 0.1.0

package/src/classify.ts

@@ -0,0 +1,208 @@
+import { DEFAULT_CONFIG, QUALITY_ORDER } from './constants';
+import type {
+  NetworkQuality,
+  NetworkQualityClassificationContext,
+  NetworkQualityConfig,
+  NetworkQualityState,
+  NetworkSnapshot,
+  ProbeResult,
+  QualitySource,
+  QualityThresholds,
+} from './types';
+
+type Classification = Pick<
+  NetworkQualityState,
+  | 'quality'
+  | 'qualitySource'
+  | 'effectiveDownlinkKbps'
+  | 'effectiveRttMs'
+  | 'reasons'
+>;
+
+type ClassifierConfig = Pick<NetworkQualityConfig, 'thresholds' | 'probe'> &
+  Partial<Pick<NetworkQualityConfig, 'validationGraceMs'>>;
+type MetricQuality = Exclude<NetworkQuality, 'unknown' | 'offline'>;
+
+function formatValue(value: number): string {
+  return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+
+function downlinkTier(
+  value: number,
+  thresholds: QualityThresholds
+): MetricQuality {
+  if (value >= thresholds.excellent.minDownlinkKbps) return 'excellent';
+  if (value >= thresholds.good.minDownlinkKbps) return 'good';
+  if (value >= thresholds.moderate.minDownlinkKbps) return 'moderate';
+  return 'poor';
+}
+
+function rttTier(value: number, thresholds: QualityThresholds): MetricQuality {
+  if (value <= thresholds.excellent.maxRttMs) return 'excellent';
+  if (value <= thresholds.good.maxRttMs) return 'good';
+  if (value <= thresholds.moderate.maxRttMs) return 'moderate';
+  return 'poor';
+}
+
+function worseQuality(
+  first: MetricQuality,
+  second: MetricQuality
+): MetricQuality {
+  const firstIndex = QUALITY_ORDER.indexOf(first);
+  const secondIndex = QUALITY_ORDER.indexOf(second);
+  return firstIndex <= secondIndex ? first : second;
+}
+
+function forcedClassification(
+  quality: 'unknown' | 'offline' | 'poor',
+  reason: string,
+  qualitySource: QualitySource = 'none'
+): Classification {
+  return {
+    quality,
+    qualitySource,
+    effectiveDownlinkKbps: null,
+    effectiveRttMs: null,
+    reasons: [reason],
+  };
+}
+
+/**
+ * Classifies a snapshot using a fresh active probe, an OS estimate, or a
+ * cellular-generation heuristic. The function is pure and deterministic.
+ */
+export function classifyNetworkQuality(
+  snapshot: NetworkSnapshot,
+  probe: ProbeResult | null,
+  config: ClassifierConfig = DEFAULT_CONFIG,
+  now: number = Date.now(),
+  context: NetworkQualityClassificationContext = {}
+): Classification {
+  if (!snapshot.isConnected) {
+    return forcedClassification('offline', 'not-connected');
+  }
+  if (snapshot.isCaptivePortal === true) {
+    return forcedClassification('poor', 'captive-portal');
+  }
+
+  const failure = context.lastProbeFailure ?? null;
+  const failureTtlMs = context.probeFailureTtlMs ?? config.probe.resultTtlMs;
+  if (
+    failure !== null &&
+    failure.transport === snapshot.transport &&
+    now - failure.timestamp <= failureTtlMs &&
+    (probe === null || failure.timestamp > probe.timestamp)
+  ) {
+    return forcedClassification(
+      'poor',
+      `probe failed: ${failure.code}`,
+      'probe'
+    );
+  }
+
+  if (snapshot.isValidated === false) {
+    const networkChangedAt = context.networkChangedAt ?? null;
+    const validationGraceMs =
+      config.validationGraceMs ?? DEFAULT_CONFIG.validationGraceMs;
+    if (
+      networkChangedAt !== null &&
+      now - networkChangedAt < validationGraceMs
+    ) {
+      return forcedClassification('unknown', 'validating');
+    }
+    return forcedClassification('poor', 'not-validated');
+  }
+
+  const reasons: string[] = [];
+  let freshProbe: ProbeResult | null = null;
+  if (probe !== null) {
+    if (probe.transport !== snapshot.transport) {
+      reasons.push('probe stale (transport changed)');
+    } else if (
+      now - probe.timestamp >
+      (context.probeResultTtlMs ?? config.probe.resultTtlMs)
+    ) {
+      reasons.push('probe stale (expired)');
+    } else {
+      freshProbe = probe;
+    }
+  }
+
+  const usedProbeDownlink = freshProbe?.downlinkKbps != null;
+  const usedProbeRtt = freshProbe?.rttMs != null;
+  const usedOsDownlink = !usedProbeDownlink && snapshot.downlinkKbps !== null;
+  const effectiveDownlinkKbps =
+    freshProbe?.downlinkKbps ?? snapshot.downlinkKbps ?? null;
+  const effectiveRttMs = freshProbe?.rttMs ?? null;
+
+  let qualitySource: QualitySource = 'none';
+  if (usedProbeDownlink || usedProbeRtt) {
+    qualitySource = 'probe';
+  } else if (usedOsDownlink) {
+    qualitySource = 'os-estimate';
+  }
+
+  let quality: MetricQuality | null = null;
+  if (effectiveDownlinkKbps !== null) {
+    const tier = downlinkTier(effectiveDownlinkKbps, config.thresholds);
+    reasons.push(
+      `downlink ${formatValue(effectiveDownlinkKbps)} kbps → ${tier}`
+    );
+    quality = tier;
+  }
+  if (effectiveRttMs !== null) {
+    const tier = rttTier(effectiveRttMs, config.thresholds);
+    reasons.push(`rtt ${formatValue(effectiveRttMs)} ms → ${tier}`);
+    quality = quality === null ? tier : worseQuality(quality, tier);
+  }
+
+  if (quality !== null) {
+    return {
+      quality,
+      qualitySource,
+      effectiveDownlinkKbps,
+      effectiveRttMs,
+      reasons,
+    };
+  }
+
+  const heuristicQuality =
+    snapshot.cellularGeneration === '5g' || snapshot.cellularGeneration === '4g'
+      ? 'good'
+      : snapshot.cellularGeneration === '3g'
+        ? 'moderate'
+        : snapshot.cellularGeneration === '2g'
+          ? 'poor'
+          : null;
+
+  if (heuristicQuality !== null) {
+    reasons.push(
+      `cellular generation ${snapshot.cellularGeneration} → ${heuristicQuality}`
+    );
+    return {
+      quality: heuristicQuality,
+      qualitySource: 'heuristic',
+      effectiveDownlinkKbps: null,
+      effectiveRttMs: null,
+      reasons,
+    };
+  }
+
+  reasons.push('no quality metrics available');
+  return {
+    quality: 'unknown',
+    qualitySource: 'none',
+    effectiveDownlinkKbps: null,
+    effectiveRttMs: null,
+    reasons,
+  };
+}
+
+/** Returns whether a ranked quality tier meets or exceeds a minimum tier. */
+export function isQualityAtLeast(
+  quality: NetworkQuality,
+  minimum: NetworkQuality
+): boolean {
+  if (quality === 'unknown' || minimum === 'unknown') return false;
+  return QUALITY_ORDER.indexOf(quality) >= QUALITY_ORDER.indexOf(minimum);
+}

package/src/constants.ts

@@ -0,0 +1,48 @@
+import type { NetworkQuality, NetworkQualityConfig } from './types';
+
+/** Default monitoring, classifier, and probe configuration. */
+export const DEFAULT_CONFIG: NetworkQualityConfig = {
+  throttleMs: 1_000,
+  bandwidthChangeThresholdPct: 10,
+  validationGraceMs: 10_000,
+  thresholds: {
+    excellent: { minDownlinkKbps: 20_000, maxRttMs: 50 },
+    good: { minDownlinkKbps: 5_000, maxRttMs: 150 },
+    moderate: { minDownlinkKbps: 1_000, maxRttMs: 400 },
+  },
+  probe: {
+    latencyUrl: 'https://www.gstatic.com/generate_204',
+    downloadUrl: 'https://speed.cloudflare.com/__down?bytes=3000000',
+    latencySamples: 3,
+    timeoutMs: 8_000,
+    downloadMaxDurationMs: 3_000,
+    downloadMaxBytes: 3_000_000,
+    resultTtlMs: 60_000,
+  },
+  autoProbe: {
+    enabled: false,
+    intervalMs: 60_000,
+    onTransportChange: true,
+    allowOnExpensive: false,
+    allowOnConstrained: false,
+  },
+};
+
+/** Ranked quality tiers from worst to best. `unknown` is intentionally unranked. */
+export const QUALITY_ORDER: NetworkQuality[] = [
+  'offline',
+  'poor',
+  'moderate',
+  'good',
+  'excellent',
+];
+
+/** Error codes that can be returned by the package. */
+export const ERROR_CODES = {
+  unsupported: 'E_UNSUPPORTED',
+  offline: 'E_OFFLINE',
+  invalidUrl: 'E_INVALID_URL',
+  probeTimeout: 'E_PROBE_TIMEOUT',
+  probeFailed: 'E_PROBE_FAILED',
+  probeSkipped: 'E_PROBE_SKIPPED',
+} as const;

package/src/errors.ts

@@ -0,0 +1,23 @@
+import type { NetworkQualityErrorCode } from './types';
+
+/** Error raised by monitoring and probing operations. */
+export class NetworkQualityError extends Error {
+  /** Stable machine-readable error code. */
+  public readonly code: NetworkQualityErrorCode;
+
+  /** Original platform error, when one is available. */
+  public override readonly cause?: unknown;
+
+  /** Creates a network-quality error with a stable code and helpful message. */
+  public constructor(
+    code: NetworkQualityErrorCode,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message);
+    this.name = 'NetworkQualityError';
+    this.code = code;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,110 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+
+import { NetworkQualityError } from './errors';
+import {
+  addNetworkQualityListener,
+  assertNetworkQualitySupported,
+  getCachedNetworkQualityState,
+  probeNetwork,
+} from './manager';
+import type { NetworkQualityState, ProbeConfig, ProbeResult } from './types';
+
+function subscribe(onStoreChange: () => void): () => void {
+  const subscription = addNetworkQualityListener(() => {
+    onStoreChange();
+  });
+  return () => subscription.remove();
+}
+
+function getServerSnapshot(): null {
+  return null;
+}
+
+/** Subscribes a React component to the referentially stable live state. */
+export function useNetworkQuality(): NetworkQualityState | null {
+  const state = useSyncExternalStore(
+    subscribe,
+    getCachedNetworkQualityState,
+    getServerSnapshot
+  );
+  assertNetworkQualitySupported();
+  return state;
+}
+
+/** State and trigger returned by `useNetworkProbe`. */
+export interface UseNetworkProbeResult {
+  /** Starts a de-duplicated active network probe. */
+  probe: (options?: Partial<ProbeConfig>) => Promise<ProbeResult>;
+  /** Whether this hook's most recent request is still running. */
+  isProbing: boolean;
+  /** Most recent successful result started by this hook. */
+  result: ProbeResult | null;
+  /** Most recent probe failure started by this hook. */
+  error: NetworkQualityError | null;
+}
+
+function asNetworkQualityError(error: unknown): NetworkQualityError {
+  return error instanceof NetworkQualityError
+    ? error
+    : new NetworkQualityError(
+        'E_PROBE_FAILED',
+        error instanceof Error ? error.message : 'The network probe failed',
+        { cause: error }
+      );
+}
+
+/** Provides imperative probing with React-friendly loading and error state. */
+export function useNetworkProbe(): UseNetworkProbeResult {
+  const mounted = useRef(true);
+  const requestId = useRef(0);
+  const [isProbing, setIsProbing] = useState(false);
+  const [result, setResult] = useState<ProbeResult | null>(null);
+  const [error, setError] = useState<NetworkQualityError | null>(null);
+
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      requestId.current += 1;
+    };
+  }, []);
+
+  const probe = useCallback(
+    async (options?: Partial<ProbeConfig>): Promise<ProbeResult> => {
+      const currentRequest = requestId.current + 1;
+      requestId.current = currentRequest;
+      if (mounted.current) {
+        setIsProbing(true);
+        setError(null);
+      }
+
+      try {
+        const nextResult = await probeNetwork(options);
+        if (mounted.current && requestId.current === currentRequest) {
+          setResult(nextResult);
+        }
+        return nextResult;
+      } catch (caught) {
+        const nextError = asNetworkQualityError(caught);
+        if (mounted.current && requestId.current === currentRequest) {
+          setError(nextError);
+        }
+        throw nextError;
+      } finally {
+        if (mounted.current && requestId.current === currentRequest) {
+          setIsProbing(false);
+        }
+      }
+    },
+    []
+  );
+
+  assertNetworkQualitySupported();
+  return { probe, isProbing, result, error };
+}

package/src/index.tsx

@@ -0,0 +1,25 @@
+/** Purely classifies a network snapshot and optional active-probe result. */
+export { classifyNetworkQuality, isQualityAtLeast } from './classify';
+
+/** Default configuration and ranked quality tiers. */
+export { DEFAULT_CONFIG, QUALITY_ORDER } from './constants';
+
+/** Error type used by all package operations. */
+export { NetworkQualityError } from './errors';
+
+/** React hooks for live state and on-demand active probes. */
+export { useNetworkProbe, useNetworkQuality } from './hooks';
+
+/** Runtime configuration, snapshots, listeners, and active probing. */
+export {
+  addNetworkQualityListener,
+  configure,
+  getConfig,
+  getLastProbeResult,
+  getNetworkQuality,
+  isSupported,
+  probeNetwork,
+} from './manager';
+
+/** Public network-quality types. */
+export type * from './types';