rn-network-quality 0.1.0

package/lib/module/classify.js

@@ -0,0 +1,126 @@
+"use strict";
+
+import { DEFAULT_CONFIG, QUALITY_ORDER } from "./constants.js";
+function formatValue(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+function downlinkTier(value, thresholds) {
+  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, thresholds) {
+  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, second) {
+  const firstIndex = QUALITY_ORDER.indexOf(first);
+  const secondIndex = QUALITY_ORDER.indexOf(second);
+  return firstIndex <= secondIndex ? first : second;
+}
+function forcedClassification(quality, reason, qualitySource = 'none') {
+  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, probe, config = DEFAULT_CONFIG, now = Date.now(), context = {}) {
+  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 = [];
+  let freshProbe = 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 = 'none';
+  if (usedProbeDownlink || usedProbeRtt) {
+    qualitySource = 'probe';
+  } else if (usedOsDownlink) {
+    qualitySource = 'os-estimate';
+  }
+  let quality = 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, minimum) {
+  if (quality === 'unknown' || minimum === 'unknown') return false;
+  return QUALITY_ORDER.indexOf(quality) >= QUALITY_ORDER.indexOf(minimum);
+}
+//# sourceMappingURL=classify.js.map

package/lib/module/classify.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_CONFIG","QUALITY_ORDER","formatValue","value","Number","isInteger","String","toFixed","downlinkTier","thresholds","excellent","minDownlinkKbps","good","moderate","rttTier","maxRttMs","worseQuality","first","second","firstIndex","indexOf","secondIndex","forcedClassification","quality","reason","qualitySource","effectiveDownlinkKbps","effectiveRttMs","reasons","classifyNetworkQuality","snapshot","probe","config","now","Date","context","isConnected","isCaptivePortal","failure","lastProbeFailure","failureTtlMs","probeFailureTtlMs","resultTtlMs","transport","timestamp","code","isValidated","networkChangedAt","validationGraceMs","freshProbe","push","probeResultTtlMs","usedProbeDownlink","downlinkKbps","usedProbeRtt","rttMs","usedOsDownlink","tier","heuristicQuality","cellularGeneration","isQualityAtLeast","minimum"],"sourceRoot":"..\\..\\src","sources":["classify.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/constants.js

@@ -0,0 +1,52 @@
+"use strict";
+
+/** Default monitoring, classifier, and probe configuration. */
+export const DEFAULT_CONFIG = {
+  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 = ['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'
+};
+//# sourceMappingURL=constants.js.map

package/lib/module/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_CONFIG","throttleMs","bandwidthChangeThresholdPct","validationGraceMs","thresholds","excellent","minDownlinkKbps","maxRttMs","good","moderate","probe","latencyUrl","downloadUrl","latencySamples","timeoutMs","downloadMaxDurationMs","downloadMaxBytes","resultTtlMs","autoProbe","enabled","intervalMs","onTransportChange","allowOnExpensive","allowOnConstrained","QUALITY_ORDER","ERROR_CODES","unsupported","offline","invalidUrl","probeTimeout","probeFailed","probeSkipped"],"sourceRoot":"..\\..\\src","sources":["constants.ts"],"mappings":";;AAEA;AACA,OAAO,MAAMA,cAAoC,GAAG;EAClDC,UAAU,EAAE,KAAK;EACjBC,2BAA2B,EAAE,EAAE;EAC/BC,iBAAiB,EAAE,MAAM;EACzBC,UAAU,EAAE;IACVC,SAAS,EAAE;MAAEC,eAAe,EAAE,MAAM;MAAEC,QAAQ,EAAE;IAAG,CAAC;IACpDC,IAAI,EAAE;MAAEF,eAAe,EAAE,KAAK;MAAEC,QAAQ,EAAE;IAAI,CAAC;IAC/CE,QAAQ,EAAE;MAAEH,eAAe,EAAE,KAAK;MAAEC,QAAQ,EAAE;IAAI;EACpD,CAAC;EACDG,KAAK,EAAE;IACLC,UAAU,EAAE,sCAAsC;IAClDC,WAAW,EAAE,mDAAmD;IAChEC,cAAc,EAAE,CAAC;IACjBC,SAAS,EAAE,KAAK;IAChBC,qBAAqB,EAAE,KAAK;IAC5BC,gBAAgB,EAAE,SAAS;IAC3BC,WAAW,EAAE;EACf,CAAC;EACDC,SAAS,EAAE;IACTC,OAAO,EAAE,KAAK;IACdC,UAAU,EAAE,MAAM;IAClBC,iBAAiB,EAAE,IAAI;IACvBC,gBAAgB,EAAE,KAAK;IACvBC,kBAAkB,EAAE;EACtB;AACF,CAAC;;AAED;AACA,OAAO,MAAMC,aAA+B,GAAG,CAC7C,SAAS,EACT,MAAM,EACN,UAAU,EACV,MAAM,EACN,WAAW,CACZ;;AAED;AACA,OAAO,MAAMC,WAAW,GAAG;EACzBC,WAAW,EAAE,eAAe;EAC5BC,OAAO,EAAE,WAAW;EACpBC,UAAU,EAAE,eAAe;EAC3BC,YAAY,EAAE,iBAAiB;EAC/BC,WAAW,EAAE,gBAAgB;EAC7BC,YAAY,EAAE;AAChB,CAAU","ignoreList":[]}

package/lib/module/errors.js

@@ -0,0 +1,18 @@
+"use strict";
+
+/** Error raised by monitoring and probing operations. */
+export class NetworkQualityError extends Error {
+  /** Stable machine-readable error code. */
+
+  /** Original platform error, when one is available. */
+
+  /** Creates a network-quality error with a stable code and helpful message. */
+  constructor(code, message, options) {
+    super(message);
+    this.name = 'NetworkQualityError';
+    this.code = code;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NetworkQualityError","Error","constructor","code","message","options","name","cause","Object","setPrototypeOf","new","target","prototype"],"sourceRoot":"..\\..\\src","sources":["errors.ts"],"mappings":";;AAEA;AACA,OAAO,MAAMA,mBAAmB,SAASC,KAAK,CAAC;EAC7C;;EAGA;;EAGA;EACOC,WAAWA,CAChBC,IAA6B,EAC7BC,OAAe,EACfC,OAA6B,EAC7B;IACA,KAAK,CAACD,OAAO,CAAC;IACd,IAAI,CAACE,IAAI,GAAG,qBAAqB;IACjC,IAAI,CAACH,IAAI,GAAGA,IAAI;IAChB,IAAI,CAACI,KAAK,GAAGF,OAAO,EAAEE,KAAK;IAC3BC,MAAM,CAACC,cAAc,CAAC,IAAI,EAAEC,GAAG,CAACC,MAAM,CAACC,SAAS,CAAC;EACnD;AACF","ignoreList":[]}

package/lib/module/hooks.js

@@ -0,0 +1,78 @@
+"use strict";
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { NetworkQualityError } from "./errors.js";
+import { addNetworkQualityListener, assertNetworkQualitySupported, getCachedNetworkQualityState, probeNetwork } from "./manager.js";
+function subscribe(onStoreChange) {
+  const subscription = addNetworkQualityListener(() => {
+    onStoreChange();
+  });
+  return () => subscription.remove();
+}
+function getServerSnapshot() {
+  return null;
+}
+
+/** Subscribes a React component to the referentially stable live state. */
+export function useNetworkQuality() {
+  const state = useSyncExternalStore(subscribe, getCachedNetworkQualityState, getServerSnapshot);
+  assertNetworkQualitySupported();
+  return state;
+}
+
+/** State and trigger returned by `useNetworkProbe`. */
+
+function asNetworkQualityError(error) {
+  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() {
+  const mounted = useRef(true);
+  const requestId = useRef(0);
+  const [isProbing, setIsProbing] = useState(false);
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      requestId.current += 1;
+    };
+  }, []);
+  const probe = useCallback(async options => {
+    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
+  };
+}
+//# sourceMappingURL=hooks.js.map

package/lib/module/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useCallback","useEffect","useRef","useState","useSyncExternalStore","NetworkQualityError","addNetworkQualityListener","assertNetworkQualitySupported","getCachedNetworkQualityState","probeNetwork","subscribe","onStoreChange","subscription","remove","getServerSnapshot","useNetworkQuality","state","asNetworkQualityError","error","Error","message","cause","useNetworkProbe","mounted","requestId","isProbing","setIsProbing","result","setResult","setError","current","probe","options","currentRequest","nextResult","caught","nextError"],"sourceRoot":"..\\..\\src","sources":["hooks.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/index.js

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

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["classifyNetworkQuality","isQualityAtLeast","DEFAULT_CONFIG","QUALITY_ORDER","NetworkQualityError","useNetworkProbe","useNetworkQuality","addNetworkQualityListener","configure","getConfig","getLastProbeResult","getNetworkQuality","isSupported","probeNetwork"],"sourceRoot":"..\\..\\src","sources":["index.tsx"],"mappings":";;AAAA;AACA,SAASA,sBAAsB,EAAEC,gBAAgB,QAAQ,eAAY;;AAErE;AACA,SAASC,cAAc,EAAEC,aAAa,QAAQ,gBAAa;;AAE3D;AACA,SAASC,mBAAmB,QAAQ,aAAU;;AAE9C;AACA,SAASC,eAAe,EAAEC,iBAAiB,QAAQ,YAAS;;AAE5D;AACA,SACEC,yBAAyB,EACzBC,SAAS,EACTC,SAAS,EACTC,kBAAkB,EAClBC,iBAAiB,EACjBC,WAAW,EACXC,YAAY,QACP,cAAW;;AAElB","ignoreList":[]}