rn-network-quality 0.1.0

package/mock.js

@@ -0,0 +1,318 @@
+'use strict';
+
+const React = require('react');
+
+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,
+  },
+};
+
+const QUALITY_ORDER = ['offline', 'poor', 'moderate', 'good', 'excellent'];
+
+class NetworkQualityError extends Error {
+  constructor(code, message, options) {
+    super(message);
+    this.name = 'NetworkQualityError';
+    this.code = code;
+    this.cause = options?.cause;
+  }
+}
+
+const GOOD_WIFI_STATE = {
+  isConnected: true,
+  isValidated: true,
+  isCaptivePortal: false,
+  transport: 'wifi',
+  isVpn: false,
+  isExpensive: false,
+  isConstrained: false,
+  isRoaming: false,
+  downlinkKbps: 10_000,
+  uplinkKbps: 5_000,
+  signalStrength: null,
+  cellularGeneration: null,
+  supportsIPv4: true,
+  supportsIPv6: true,
+  supportsDNS: true,
+  unsatisfiedReason: null,
+  timestamp: 0,
+  quality: 'good',
+  qualitySource: 'os-estimate',
+  effectiveDownlinkKbps: 10_000,
+  effectiveRttMs: null,
+  lastProbe: null,
+  lastProbeFailure: null,
+  reasons: ['downlink 10000 kbps → good'],
+};
+
+const GOOD_PROBE_RESULT = {
+  rttMs: 75,
+  downlinkKbps: 10_000,
+  bytesReceived: 200_000,
+  durationMs: 250,
+  transport: 'wifi',
+  downloadError: null,
+  timestamp: 0,
+};
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+let config = clone(DEFAULT_CONFIG);
+let lastProbe = null;
+
+function classifyNetworkQuality(
+  snapshot,
+  probe,
+  classifierConfig = config,
+  now = Date.now(),
+  context = {}
+) {
+  if (!snapshot.isConnected) {
+    return classification('offline', 'none', null, null, ['not-connected']);
+  }
+  if (snapshot.isCaptivePortal === true) {
+    return classification('poor', 'none', null, null, ['captive-portal']);
+  }
+  const failure = context.lastProbeFailure ?? null;
+  if (
+    failure !== null &&
+    failure.transport === snapshot.transport &&
+    now - failure.timestamp <=
+      (context.probeFailureTtlMs ?? classifierConfig.probe.resultTtlMs) &&
+    (probe === null || failure.timestamp > probe.timestamp)
+  ) {
+    return classification('poor', 'probe', null, null, [
+      `probe failed: ${failure.code}`,
+    ]);
+  }
+  if (snapshot.isValidated === false) {
+    const networkChangedAt = context.networkChangedAt ?? null;
+    if (
+      networkChangedAt !== null &&
+      now - networkChangedAt < classifierConfig.validationGraceMs
+    ) {
+      return classification('unknown', 'none', null, null, ['validating']);
+    }
+    return classification('poor', 'none', null, null, ['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 ?? classifierConfig.probe.resultTtlMs)
+    ) {
+      reasons.push('probe stale (expired)');
+    } else {
+      freshProbe = probe;
+    }
+  }
+
+  const usedProbeDownlink = freshProbe?.downlinkKbps != null;
+  const usedProbeRtt = freshProbe?.rttMs != null;
+  const downlink = freshProbe?.downlinkKbps ?? snapshot.downlinkKbps ?? null;
+  const rtt = freshProbe?.rttMs ?? null;
+  const tiers = [];
+  if (downlink !== null) {
+    const tier = downlinkTier(downlink, classifierConfig.thresholds);
+    tiers.push(tier);
+    reasons.push(`downlink ${downlink} kbps → ${tier}`);
+  }
+  if (rtt !== null) {
+    const tier = rttTier(rtt, classifierConfig.thresholds);
+    tiers.push(tier);
+    reasons.push(`rtt ${rtt} ms → ${tier}`);
+  }
+  if (tiers.length > 0) {
+    const quality = tiers.reduce((worst, tier) =>
+      QUALITY_ORDER.indexOf(tier) < QUALITY_ORDER.indexOf(worst) ? tier : worst
+    );
+    return classification(
+      quality,
+      usedProbeDownlink || usedProbeRtt ? 'probe' : 'os-estimate',
+      downlink,
+      rtt,
+      reasons
+    );
+  }
+
+  const heuristic =
+    snapshot.cellularGeneration === '4g' || snapshot.cellularGeneration === '5g'
+      ? 'good'
+      : snapshot.cellularGeneration === '3g'
+        ? 'moderate'
+        : snapshot.cellularGeneration === '2g'
+          ? 'poor'
+          : 'unknown';
+  return classification(
+    heuristic,
+    heuristic === 'unknown' ? 'none' : 'heuristic',
+    null,
+    null,
+    [
+      heuristic === 'unknown'
+        ? 'no quality metrics available'
+        : `cellular generation ${snapshot.cellularGeneration} → ${heuristic}`,
+    ]
+  );
+}
+
+function classification(quality, qualitySource, downlink, rtt, reasons) {
+  return {
+    quality,
+    qualitySource,
+    effectiveDownlinkKbps: downlink,
+    effectiveRttMs: rtt,
+    reasons,
+  };
+}
+
+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 isQualityAtLeast(quality, minimum) {
+  if (quality === 'unknown' || minimum === 'unknown') return false;
+  return QUALITY_ORDER.indexOf(quality) >= QUALITY_ORDER.indexOf(minimum);
+}
+
+function isSupported() {
+  return true;
+}
+
+function configure(patch) {
+  config = {
+    ...config,
+    ...patch,
+    thresholds: {
+      ...config.thresholds,
+      ...patch.thresholds,
+      excellent: {
+        ...config.thresholds.excellent,
+        ...patch.thresholds?.excellent,
+      },
+      good: { ...config.thresholds.good, ...patch.thresholds?.good },
+      moderate: {
+        ...config.thresholds.moderate,
+        ...patch.thresholds?.moderate,
+      },
+    },
+    probe: { ...config.probe, ...patch.probe },
+    autoProbe: { ...config.autoProbe, ...patch.autoProbe },
+  };
+}
+
+function getConfig() {
+  return clone(config);
+}
+
+function getNetworkQuality() {
+  return Promise.resolve(GOOD_WIFI_STATE);
+}
+
+function addNetworkQualityListener(listener) {
+  let active = true;
+  Promise.resolve().then(() => {
+    if (active) listener(GOOD_WIFI_STATE);
+  });
+  return {
+    remove() {
+      active = false;
+    },
+  };
+}
+
+function probeNetwork() {
+  lastProbe = GOOD_PROBE_RESULT;
+  return Promise.resolve(GOOD_PROBE_RESULT);
+}
+
+function getLastProbeResult() {
+  return lastProbe;
+}
+
+function useNetworkQuality() {
+  return GOOD_WIFI_STATE;
+}
+
+function useNetworkProbe() {
+  const mounted = React.useRef(true);
+  const [isProbing, setIsProbing] = React.useState(false);
+  const [result, setResult] = React.useState(null);
+  const [error, setError] = React.useState(null);
+  React.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  const probe = React.useCallback(async (options) => {
+    setIsProbing(true);
+    setError(null);
+    try {
+      const nextResult = await probeNetwork(options);
+      if (mounted.current) setResult(nextResult);
+      return nextResult;
+    } catch (nextError) {
+      if (mounted.current) setError(nextError);
+      throw nextError;
+    } finally {
+      if (mounted.current) setIsProbing(false);
+    }
+  }, []);
+  return { probe, isProbing, result, error };
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  QUALITY_ORDER,
+  NetworkQualityError,
+  classifyNetworkQuality,
+  isQualityAtLeast,
+  isSupported,
+  configure,
+  getConfig,
+  getNetworkQuality,
+  addNetworkQualityListener,
+  probeNetwork,
+  getLastProbeResult,
+  useNetworkQuality,
+  useNetworkProbe,
+};

package/package.json

@@ -0,0 +1,161 @@
+{
+  "name": "rn-network-quality",
+  "version": "0.1.0",
+  "description": "Live network quality signals for React Native — bandwidth, link quality and connectivity via a New Architecture TurboModule",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "react-native": "./src/index.tsx",
+  "source": "./src/index.tsx",
+  "exports": {
+    ".": {
+      "rn-network-quality-source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./mock": "./mock.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "*.podspec",
+    "mock.js",
+    "!ios/build",
+    "!android/build",
+    "!android/.gradle",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!android/src/test",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace rn-network-quality-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "test": "jest",
+    "test:coverage": "jest --coverage --runInBand",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "lint:fix": "yarn lint --fix",
+    "codegen:check": "node scripts/check-codegen.mjs",
+    "pack:check": "node scripts/check-package.mjs",
+    "commitlint": "commitlint",
+    "release": "release-it"
+  },
+  "keywords": [
+    "react-native",
+    "network",
+    "network-quality",
+    "bandwidth",
+    "connectivity",
+    "turbomodule",
+    "new-architecture",
+    "nwpathmonitor",
+    "networkcapabilities",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kruthikRgowda/rn-network-quality"
+  },
+  "author": "kruthik <kruthikbr2@gmail.com> (https://github.com/kruthikRgowda)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kruthikRgowda/rn-network-quality/issues"
+  },
+  "homepage": "https://github.com/kruthikRgowda/rn-network-quality",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.3",
+    "@commitlint/config-conventional": "^21.2.3",
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.6",
+    "@eslint/js": "^9.39.5",
+    "@react-native/babel-preset": "0.87.1",
+    "@react-native/eslint-config": "0.87.1",
+    "@react-native/jest-preset": "0.87.1",
+    "@release-it/conventional-changelog": "^12.0.2",
+    "@testing-library/react-native": "13.3.3",
+    "@types/jest": "30.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-test-renderer": "^19",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "29.7.0",
+    "lefthook": "^2.1.14",
+    "prettier": "^3.9.8",
+    "react": "19.2.3",
+    "react-native": "0.87.1",
+    "react-native-builder-bob": "^0.43.1",
+    "react-test-renderer": "19.2.3",
+    "release-it": "^21.1.0",
+    "turbo": "^2.10.8",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.80.0"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "RNNetworkQualitySpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.rnnetworkquality"
+    },
+    "ios": {
+      "modules": {
+        "NetworkQuality": {
+          "className": "NetworkQuality",
+          "unstableRequiresMainQueueSetup": false
+        }
+      }
+    }
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint"
+    ],
+    "version": "0.63.1"
+  }
+}

package/rn-network-quality.podspec

@@ -0,0 +1,32 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "rn-network-quality"
+  s.module_name  = "rn_network_quality"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = {
+    :git => "https://github.com/kruthikRgowda/rn-network-quality",
+    :tag => "v#{s.version}"
+  }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift}"
+  # The adapter header imports a C++ Codegen interface and must stay out of the
+  # Swift module umbrella. The ObjC++ implementation includes it directly.
+  s.private_header_files = "ios/NetworkQuality.h"
+  s.frameworks = "Network", "CoreTelephony"
+  s.swift_version = "5.9"
+  s.pod_target_xcconfig = { "DEFINES_MODULE" => "YES" }
+  s.resource_bundles = {
+    "RNNetworkQualityPrivacy" => ["ios/PrivacyInfo.xcprivacy"]
+  }
+
+  install_modules_dependencies(s)
+end

package/src/NativeNetworkQuality.ts

@@ -0,0 +1,58 @@
+import {
+  TurboModuleRegistry,
+  type CodegenTypes,
+  type TurboModule,
+} from 'react-native';
+
+export type NativeNetworkSnapshot = {
+  isConnected: boolean;
+  isValidated: boolean | null;
+  isCaptivePortal: boolean | null;
+  transport: string;
+  isVpn: boolean | null;
+  isExpensive: boolean;
+  isConstrained: boolean;
+  isRoaming: boolean | null;
+  downlinkKbps: number | null;
+  uplinkKbps: number | null;
+  signalStrength: number | null;
+  cellularGeneration: string | null;
+  supportsIPv4: boolean | null;
+  supportsIPv6: boolean | null;
+  supportsDNS: boolean | null;
+  unsatisfiedReason: string | null;
+  timestamp: number;
+};
+
+export type NativeMonitorOptions = {
+  throttleMs: number;
+  bandwidthChangeThresholdPct: number;
+};
+
+export type NativeProbeOptions = {
+  latencyUrl: string;
+  downloadUrl: string | null;
+  latencySamples: number;
+  timeoutMs: number;
+  downloadMaxDurationMs: number;
+  downloadMaxBytes: number;
+};
+
+export type NativeProbeResult = {
+  rttMs: number | null;
+  downlinkKbps: number | null;
+  bytesReceived: number;
+  durationMs: number;
+  downloadError: string | null;
+  timestamp: number;
+};
+
+export interface Spec extends TurboModule {
+  getCurrentState(): Promise<NativeNetworkSnapshot>;
+  startMonitoring(options: NativeMonitorOptions): void;
+  stopMonitoring(): void;
+  probe(options: NativeProbeOptions): Promise<NativeProbeResult>;
+  readonly onNetworkStateChange: CodegenTypes.EventEmitter<NativeNetworkSnapshot>;
+}
+
+export default TurboModuleRegistry.get<Spec>('NetworkQuality');