react-native-nitro-compass 0.1.0

package/package.json

@@ -0,0 +1,136 @@
+{
+  "name": "react-native-nitro-compass",
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "description": "Fast, accurate compass heading for React Native, powered by Nitro Modules. Uses Android TYPE_ROTATION_VECTOR sensor fusion and iOS CLHeading.",
+  "main": "./lib/commonjs/index.js",
+  "module": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "react-native": "src/index",
+  "source": "src/index",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "clean": "git clean -dfX",
+    "release": "semantic-release",
+    "build": "npm run typecheck && bob build",
+    "prepare": "bob build",
+    "codegen": "nitrogen --logLevel=\"debug\" && npm run build"
+  },
+  "keywords": [
+    "react-native",
+    "nitro",
+    "nitro-modules",
+    "compass",
+    "heading",
+    "magnetometer",
+    "qibla",
+    "rotation-vector",
+    "ios",
+    "android"
+  ],
+  "files": [
+    "src",
+    "!src/__tests__",
+    "react-native.config.js",
+    "lib",
+    "!lib/typescript/src/__tests__",
+    "nitrogen",
+    "cpp",
+    "nitro.json",
+    "android/build.gradle",
+    "android/fix-prefab.gradle",
+    "android/gradle.properties",
+    "android/CMakeLists.txt",
+    "android/src",
+    "ios/**/*.h",
+    "ios/**/*.m",
+    "ios/**/*.mm",
+    "ios/**/*.cpp",
+    "ios/**/*.swift",
+    "app.plugin.js",
+    "*.podspec",
+    "README.md"
+  ],
+  "repository": "https://github.com/omarsdev/react-native-nitro-compass.git",
+  "author": "Omar Sukarieh",
+  "license": "MIT",
+  "bugs": "https://github.com/omarsdev/react-native-nitro-compass/issues",
+  "homepage": "https://github.com/omarsdev/react-native-nitro-compass#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@jamesacarr/eslint-formatter-github-actions": "^0.2.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/jest": "^29.5.12",
+    "@types/react": "19.2.0",
+    "babel-jest": "^30.3.0",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "jest": "^30.3.0",
+    "nitrogen": "0.35.6",
+    "react": "19.2.3",
+    "react-native": "0.84.1",
+    "react-native-builder-bob": "^0.40.18",
+    "react-native-nitro-modules": "0.35.6",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": "*"
+  },
+  "eslintConfig": {
+    "root": true,
+    "extends": [
+      "@react-native",
+      "prettier"
+    ],
+    "plugins": [
+      "prettier"
+    ],
+    "rules": {
+      "prettier/prettier": [
+        "warn",
+        {
+          "quoteProps": "consistent",
+          "singleQuote": true,
+          "tabWidth": 2,
+          "trailingComma": "es5",
+          "useTabs": false
+        }
+      ]
+    }
+  },
+  "eslintIgnore": [
+    "node_modules/",
+    "lib/"
+  ],
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false,
+    "semi": false
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.json"
+        }
+      ]
+    ]
+  }
+}

package/react-native.config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        packageImportPath:
+          'import com.margelo.nitro.nitrocompass.NitroCompassPackage;',
+        packageInstance: 'new NitroCompassPackage()',
+      },
+    },
+  },
+}

package/src/hook.ts

@@ -0,0 +1,118 @@
+import { useEffect, useRef, useState } from 'react'
+import type {
+  AccuracyQuality,
+  CompassSample,
+  SensorDiagnostics,
+} from './specs/NitroCompass.nitro'
+import { NitroCompass } from './native'
+import {
+  addCalibrationListener,
+  addHeadingListener,
+  addInterferenceListener,
+} from './multiplex'
+
+export interface UseCompassOptions {
+  /**
+   * Minimum change between samples in degrees. Pass `0` for "every
+   * event". Default `1`. Updated live via `NitroCompass.setFilter()`.
+   * Note: this is global state shared with any other consumer of
+   * the library — last-write-wins.
+   */
+  filterDegrees?: number
+  /**
+   * Magnetic-to-true offset in signed degrees. Default `0` (magnetic).
+   * Pull from a model like `geomagnetism` keyed on the user's lat/lon.
+   * Like `filterDegrees`, this is shared global state.
+   */
+  declination?: number
+  /**
+   * Pause the underlying sensor when the app is backgrounded. Default
+   * `true`. Shared global state.
+   */
+  pauseOnBackground?: boolean
+  /**
+   * Toggle the heading subscription without unmounting the hook.
+   * Default `true`. When `false`, the hook still observes calibration
+   * and interference (so you can show warnings) but won't tear down
+   * its own state — `reading` simply stops updating.
+   */
+  enabled?: boolean
+}
+
+export interface UseCompassResult {
+  /** Latest emitted sample, or `null` until the first arrives. */
+  reading: CompassSample | null
+  /** Coarse accuracy bucket, or `null` until the first transition. */
+  quality: AccuracyQuality | null
+  /** Whether external magnetic interference is currently detected. */
+  interfering: boolean
+  /** Hardware availability — read once on first render. */
+  hasCompass: boolean
+  /** Which sensor backs the readings on this device. */
+  diagnostics: SensorDiagnostics | undefined
+}
+
+/**
+ * Ergonomic React wrapper for the NitroCompass surface. Handles
+ * subscription lifecycle, callback registration, and the live-tuneable
+ * knobs. Multiple instances mounted at once safely share the same
+ * underlying native subscription via the multi-listener primitives in
+ * `./multiplex`.
+ */
+export function useCompass(
+  options: UseCompassOptions = {}
+): UseCompassResult {
+  const {
+    filterDegrees = 1,
+    declination = 0,
+    pauseOnBackground = true,
+    enabled = true,
+  } = options
+
+  const [reading, setReading] = useState<CompassSample | null>(null)
+  const [quality, setQuality] = useState<AccuracyQuality | null>(null)
+  const [interfering, setInterfering] = useState(false)
+
+  const [hasCompass] = useState(() => NitroCompass.hasCompass())
+  const [diagnostics] = useState(() => NitroCompass.getDiagnostics())
+
+  // Tracked via ref so the heading-subscription effect can re-apply
+  // the user's filter after a stop/start cycle without restarting on
+  // every filterDegrees change.
+  const filterRef = useRef(filterDegrees)
+  filterRef.current = filterDegrees
+
+  useEffect(() => {
+    NitroCompass.setFilter(filterDegrees)
+  }, [filterDegrees])
+
+  useEffect(() => {
+    NitroCompass.setDeclination(declination)
+  }, [declination])
+
+  useEffect(() => {
+    NitroCompass.setPauseOnBackground(pauseOnBackground)
+  }, [pauseOnBackground])
+
+  useEffect(() => {
+    if (!hasCompass) return
+    return addCalibrationListener(setQuality)
+  }, [hasCompass])
+
+  useEffect(() => {
+    if (!hasCompass) return
+    return addInterferenceListener(setInterfering)
+  }, [hasCompass])
+
+  useEffect(() => {
+    if (!hasCompass || !enabled) return
+    const off = addHeadingListener(setReading)
+    // Multiplex starts the sensor with a default filter; re-apply the
+    // current option after subscribing.
+    NitroCompass.setFilter(filterRef.current)
+    return off
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hasCompass, enabled])
+
+  return { reading, quality, interfering, hasCompass, diagnostics }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import type {
+  AccuracyQuality,
+  CompassSample,
+  NitroCompass as NitroCompassSpec,
+  PermissionStatus,
+  SensorDiagnostics,
+  SensorKind,
+} from './specs/NitroCompass.nitro'
+
+export { NitroCompass } from './native'
+
+export type {
+  AccuracyQuality,
+  CompassSample,
+  PermissionStatus,
+  SensorDiagnostics,
+  SensorKind,
+}
+export type { NitroCompassSpec as NitroCompassHybridObject }
+
+export {
+  addCalibrationListener,
+  addHeadingListener,
+  addInterferenceListener,
+} from './multiplex'
+
+export { useCompass } from './hook'
+export type { UseCompassOptions, UseCompassResult } from './hook'

package/src/multiplex.ts

@@ -0,0 +1,117 @@
+/**
+ * JS-side fan-out so multiple consumers can subscribe to the same
+ * compass stream without clobbering each other. The native API is
+ * single-callback by design (start, setOnCalibrationNeeded,
+ * setOnInterferenceDetected each own one slot); these helpers wrap
+ * that into multi-listener primitives with reference-counted
+ * lifecycle.
+ *
+ * Mixing direct `NitroCompass.start()` / `setOnCalibrationNeeded()` /
+ * `setOnInterferenceDetected()` calls with these helpers will
+ * clobber the multiplex's internal callback slot — pick one path.
+ */
+import type {
+  AccuracyQuality,
+  CompassSample,
+} from './specs/NitroCompass.nitro'
+import { NitroCompass } from './native'
+
+type HeadingListener = (sample: CompassSample) => void
+type CalibrationListener = (quality: AccuracyQuality) => void
+type InterferenceListener = (interferenceDetected: boolean) => void
+
+const headingListeners = new Set<HeadingListener>()
+const calibrationListeners = new Set<CalibrationListener>()
+const interferenceListeners = new Set<InterferenceListener>()
+
+let calibrationRegistered = false
+let interferenceRegistered = false
+
+const DEFAULT_FILTER_DEG = 1
+
+function dispatchHeading(sample: CompassSample) {
+  for (const cb of Array.from(headingListeners)) {
+    try {
+      cb(sample)
+    } catch (e) {
+      console.error('[NitroCompass] heading listener threw:', e)
+    }
+  }
+}
+
+function dispatchCalibration(quality: AccuracyQuality) {
+  for (const cb of Array.from(calibrationListeners)) {
+    try {
+      cb(quality)
+    } catch (e) {
+      console.error('[NitroCompass] calibration listener threw:', e)
+    }
+  }
+}
+
+function dispatchInterference(detected: boolean) {
+  for (const cb of Array.from(interferenceListeners)) {
+    try {
+      cb(detected)
+    } catch (e) {
+      console.error('[NitroCompass] interference listener threw:', e)
+    }
+  }
+}
+
+/**
+ * Subscribe to heading samples. The first listener implicitly calls
+ * `NitroCompass.start()`; the last `unsubscribe()` calls
+ * `NitroCompass.stop()`. Returns the unsubscribe function.
+ *
+ * Filter, declination, and pauseOnBackground remain global state on
+ * `NitroCompass` and are shared across all listeners — call
+ * `NitroCompass.setFilter()` etc. directly to tune them.
+ */
+export function addHeadingListener(cb: HeadingListener): () => void {
+  const wasEmpty = headingListeners.size === 0
+  headingListeners.add(cb)
+  if (wasEmpty) {
+    NitroCompass.start(DEFAULT_FILTER_DEG, dispatchHeading)
+  }
+  return () => {
+    if (!headingListeners.delete(cb)) return
+    if (headingListeners.size === 0) {
+      NitroCompass.stop()
+    }
+  }
+}
+
+/**
+ * Subscribe to calibration-bucket transitions. Only fires while a
+ * heading subscription is active. Returns the unsubscribe function.
+ */
+export function addCalibrationListener(
+  cb: CalibrationListener
+): () => void {
+  if (!calibrationRegistered) {
+    NitroCompass.setOnCalibrationNeeded(dispatchCalibration)
+    calibrationRegistered = true
+  }
+  calibrationListeners.add(cb)
+  return () => {
+    calibrationListeners.delete(cb)
+  }
+}
+
+/**
+ * Subscribe to magnetic-interference transitions. Only fires while a
+ * heading subscription is active. Returns the unsubscribe function.
+ */
+export function addInterferenceListener(
+  cb: InterferenceListener
+): () => void {
+  if (!interferenceRegistered) {
+    NitroCompass.setOnInterferenceDetected(dispatchInterference)
+    interferenceRegistered = true
+  }
+  interferenceListeners.add(cb)
+  return () => {
+    interferenceListeners.delete(cb)
+  }
+}

package/src/native.ts

@@ -0,0 +1,5 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { NitroCompass as NitroCompassSpec } from './specs/NitroCompass.nitro'
+
+export const NitroCompass =
+  NitroModules.createHybridObject<NitroCompassSpec>('NitroCompass')

package/src/specs/NitroCompass.nitro.ts

@@ -0,0 +1,193 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * One compass heading sample, delivered to the JS callback registered with
+ * `start()`. Both fields are in degrees.
+ *
+ * - `heading`: heading clockwise from north, in `[0, 360)`. Magnetic by
+ *   default; if you call `setDeclination(deg)` the offset is applied
+ *   natively before this sample is delivered (and reflected in
+ *   `getCurrentHeading()`).
+ * - `accuracy`: estimated heading uncertainty in degrees, or `-1` when the
+ *   platform has not yet reported a usable accuracy. Smaller is better.
+ *   On Android this is read from `event.values[4]` of the rotation-vector
+ *   sensor when available, otherwise mapped from `SensorManager.SENSOR_STATUS_*`.
+ *   On iOS this is `CLHeading.headingAccuracy`.
+ */
+export interface CompassSample {
+  heading: number
+  accuracy: number
+}
+
+/**
+ * Coarse calibration bucket reported via `setOnCalibrationNeeded`. Buckets
+ * are derived from numeric heading accuracy on both platforms (same
+ * thresholds), so values agree across iOS and Android:
+ *
+ *   `<5°` → `high`, `<15°` → `medium`, `<30°` → `low`, otherwise `unreliable`.
+ *
+ * On iOS `unreliable` is also reported when the system asks to display
+ * its built-in calibration UI (we suppress it).
+ */
+export type AccuracyQuality = 'high' | 'medium' | 'low' | 'unreliable'
+
+/**
+ * Identifies which underlying sensor / framework is producing headings.
+ *
+ * - `rotationVector` — Android `Sensor.TYPE_ROTATION_VECTOR` (gyro + accel
+ *   + magnetometer fused). Best quality.
+ * - `geomagneticRotationVector` — Android
+ *   `Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTOR` (accel + magnetometer only).
+ *   Used as fallback on gyroless / budget devices; lower update rate and
+ *   more susceptible to magnetic interference.
+ * - `coreLocation` — iOS `CLLocationManager` heading. Apple's stack
+ *   handles fusion natively.
+ */
+export type SensorKind =
+  | 'rotationVector'
+  | 'geomagneticRotationVector'
+  | 'coreLocation'
+
+export interface SensorDiagnostics {
+  sensor: SensorKind
+}
+
+/**
+ * Platform permission state required to deliver headings.
+ *
+ * - `granted` — headings will deliver. iOS: `authorizedAlways` /
+ *   `authorizedWhenInUse`. Android: always (sensors require no permission).
+ * - `denied` — user has refused or the OS has restricted access (e.g.
+ *   parental controls). On iOS, `start()` will throw with this status.
+ * - `unknown` — iOS `notDetermined`: nothing has been asked yet. Calling
+ *   `requestPermission()` is the way to resolve from `unknown` to
+ *   `granted`/`denied`.
+ */
+export type PermissionStatus = 'granted' | 'denied' | 'unknown'
+
+/**
+ * Native compass module. Pull this from `NitroModules.createHybridObject`
+ * via the bundled `NitroCompass` export, e.g.:
+ *
+ * ```ts
+ * import { NitroCompass } from 'react-native-nitro-compass'
+ *
+ * NitroCompass.start(1, ({ heading, accuracy }) => {
+ *   console.log(heading, accuracy)
+ * })
+ * NitroCompass.stop()
+ * ```
+ */
+export interface NitroCompass extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /**
+   * Begin emitting heading samples to `onHeading`. If `start()` has already
+   * been called without a matching `stop()`, the previous subscription is
+   * silently torn down and replaced — the old `onHeading` is detached.
+   *
+   * @param filterDegrees Minimum change (in degrees) between samples before
+   *   the next one is emitted. Pass `0` for "every event"; typical UI values
+   *   are 1–3. Use `setFilter()` to update without restarting.
+   * @param onHeading JS callback invoked on each accepted sample. Called on
+   *   the JS thread; calling `stop()` from inside this callback is safe.
+   */
+  start(filterDegrees: number, onHeading: (sample: CompassSample) => void): void
+
+  /** Stop the underlying sensor / location-manager subscription. Idempotent — safe to call when not started. */
+  stop(): void
+
+  /** Whether `start()` has been called without a matching `stop()`. */
+  isStarted(): boolean
+
+  /**
+   * Update the deadband filter live without tearing down the subscription.
+   * Same semantics as the `filterDegrees` argument to `start()`. Has no
+   * effect until `start()` is called.
+   */
+  setFilter(degrees: number): void
+
+  /**
+   * Describe which underlying sensor / framework would produce headings on
+   * this device. Returns `undefined` if the device has no compass hardware
+   * (equivalent to `hasCompass() === false`). Safe to call before `start()`.
+   */
+  getDiagnostics(): SensorDiagnostics | undefined
+
+  /**
+   * Whether the device has the hardware required for a compass reading.
+   * Android: a rotation-vector sensor (fused or geomagnetic) is present.
+   * iOS: `CLLocationManager.headingAvailable()`.
+   */
+  hasCompass(): boolean
+
+  /**
+   * Last sample emitted by the active subscription, with declination
+   * already applied. Returns `undefined` when not started, or when started
+   * but no sample has arrived yet.
+   */
+  getCurrentHeading(): CompassSample | undefined
+
+  /**
+   * Magnetic-to-true offset (degrees, signed) added to every heading
+   * before it leaves the native side. Pass `0` to revert to magnetic.
+   * Survives across `start`/`stop`. Apply your own declination from a
+   * model like `geomagnetism` keyed on the user's lat/lon.
+   */
+  setDeclination(degrees: number): void
+
+  /**
+   * Register a callback fired when the calibration bucket transitions.
+   * Replaces any previously registered callback. Pass a no-op to mute.
+   * The callback is invoked on the JS thread.
+   */
+  setOnCalibrationNeeded(onChange: (quality: AccuracyQuality) => void): void
+
+  /**
+   * Register a callback fired when external magnetic interference is
+   * detected — typical sources are laptops, monitors, car engines, and
+   * large steel structures, all of which can skew heading by tens of
+   * degrees while the calibration bucket still reads `'medium'` or
+   * better. Fires `true` when the raw magnetic field magnitude leaves
+   * the normal Earth band (~20–70 µT) and `false` when it returns.
+   * Only transitions are reported; the callback is debounce-free, so
+   * brief excursions still fire.
+   *
+   * Replaces any previously registered callback. Pass a no-op to mute.
+   * The callback is invoked on the JS thread. Only meaningful while
+   * `start()` is active.
+   *
+   * iOS uses `CMDeviceMotion.magneticField` — the calibrated field
+   * with the device's own hard-iron bias subtracted in real time.
+   * No transitions are reported until CoreMotion's bias estimate
+   * converges (a second or two of normal device movement); that's
+   * required, otherwise raw readings dominated by internal bias
+   * would fire false alarms continuously.
+   */
+  setOnInterferenceDetected(onChange: (interferenceDetected: boolean) => void): void
+
+  /**
+   * Toggle automatic pause/resume on app background/foreground. Default
+   * `true`. When enabled, the underlying sensor / location-manager
+   * subscription is silently paused while the app is backgrounded and
+   * resumed when it returns to the foreground; the JS callback and
+   * declination are preserved across the pause. Call before or after
+   * `start()`; takes effect immediately.
+   */
+  setPauseOnBackground(enabled: boolean): void
+
+  /**
+   * Read the current platform permission state synchronously.
+   * On Android this is always `'granted'` (sensors require no permission);
+   * on iOS it maps `CLLocationManager.authorizationStatus`.
+   */
+  getPermissionStatus(): PermissionStatus
+
+  /**
+   * Request the platform permission required to deliver headings. On iOS
+   * this prompts the system "Allow location" dialog if the status is
+   * `'unknown'` and resolves once the user makes a choice. If already
+   * `'granted'` or `'denied'` it resolves immediately with that value
+   * (iOS does not re-prompt). On Android it resolves immediately with
+   * `'granted'`.
+   */
+  requestPermission(): Promise<PermissionStatus>
+}