@inoxialabs/react-native-nitro-location-geocoder 0.1.0 → 1.0.1

package/NitroLocationGeocoder.podspec

@@ -1,28 +1,28 @@
-require "json"
-
-package = JSON.parse(File.read(File.join(__dir__, "package.json")))
-
-Pod::Spec.new do |s|
-  s.name         = "NitroLocationGeocoder"
-  s.version      = package["version"]
-  s.summary      = package["description"]
-  s.homepage     = package["homepage"] || "https://github.com"
-  s.license      = package["license"] || "Apache-2.0"
-  s.authors      = package["author"] || "Inoxia Labs"
-
-  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
-  s.source       = { :path => "." }
-
-  s.source_files = [
-    "ios/**/*.{swift}",
-    "ios/**/*.{m,mm}",
-    "cpp/**/*.{hpp,cpp}",
-  ]
-
-  load "nitrogen/generated/ios/NitroLocationGeocoder+autolinking.rb"
-  add_nitrogen_files(s)
-
-  s.dependency "React-jsi"
-  s.dependency "React-callinvoker"
-  install_modules_dependencies(s)
-end
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroLocationGeocoder"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"] || "https://github.com"
+  s.license      = package["license"] || "Apache-2.0"
+  s.authors      = package["author"] || "Inoxia Labs"
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :path => "." }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  load "nitrogen/generated/ios/NitroLocationGeocoder+autolinking.rb"
+  add_nitrogen_files(s)
+
+  s.dependency "React-jsi"
+  s.dependency "React-callinvoker"
+  install_modules_dependencies(s)
+end

package/README.md

@@ -1,80 +1,120 @@
-# @inoxialabs/react-native-nitro-location-geocoder
-
-`@inoxialabs/react-native-nitro-location-geocoder` is a minimal React Native Nitro module for reverse geocoding latitude and longitude coordinates into normalized country and locality data.
-
-## Features
-
-- Native reverse geocoding on both platforms.
-- Locale-aware lookups through a language tag such as `en`, `es`, or `es-PE`.
-- Normalized result shape for country, locality, and administrative subdivisions.
-- Promise-based API exposed through `react-native-nitro-modules`.
-- No product-specific logic or backend dependencies.
-
-## Installation
-
-```bash
-npm install @inoxialabs/react-native-nitro-location-geocoder react-native-nitro-modules
-```
-
-Peer dependencies:
-
-- `react`
-- `react-native`
-- `react-native-nitro-modules`
-
-iOS:
-
-```bash
-cd ios && pod install
-```
-
-## Usage
-
-```ts
-import { reverseGeocode } from '@inoxialabs/react-native-nitro-location-geocoder';
-
-const result = await reverseGeocode(4.711, -74.0721, 'es-CO');
-
-console.log(result.countryCode);
-console.log(result.country);
-console.log(result.locality);
-```
-
-## API
-
-### `reverseGeocode(latitude, longitude, locale)`
-
-Returns `Promise<LocationGeocoderResult>`.
-
-`LocationGeocoderResult` fields:
-
-- `countryCode`
-- `country`
-- `locality`
-- `administrativeArea`
-- `subAdministrativeArea`
-- `subLocality`
-
-## Platform behavior
-
-- iOS uses `CLGeocoder`.
-- Android uses `android.location.Geocoder`.
-- Empty fields are returned as empty strings when the platform geocoder does not provide a value.
-- The module rejects when the platform geocoder fails or returns no results.
-- Common error values include `NO_RESULTS`, `UNAVAILABLE`, `GEOCODER_TIMEOUT`, or platform geocoder error messages.
-
-## Development
-
-Regenerate Nitro bindings after changing the `.nitro.ts` spec or `nitro.json`:
-
-```bash
-npm install
-npm run specs
-npm test
-```
-
-Validate the package contents before publishing:
-
-```bash
-npm pack --dry-run
-```
+# @inoxialabs/react-native-nitro-location-geocoder
+
+`@inoxialabs/react-native-nitro-location-geocoder` is a minimal React Native Nitro module for reverse geocoding latitude and longitude coordinates into a normalized location result.
+
+## Features
+
+- Reverse geocoding on iOS and Android.
+- Locale-aware lookups using language tags. For example: `en`, `es`, or `es-PE`.
+- Small, typed API with a normalized result shape.
+- No backend dependency and no device location permission requirement.
+- Stable generic errors for unavailable geocoders, empty results, invalid coordinates, timeouts, and native geocoder failures.
+
+## Supported platforms
+
+- iOS
+- Android
+
+This package does not expose a web implementation.
+
+## Installation
+
+Install the package and its Nitro peer dependency:
+
+```bash
+npm install @inoxialabs/react-native-nitro-location-geocoder react-native-nitro-modules
+```
+
+Peer dependencies:
+
+- `react`
+- `react-native`
+- `react-native-nitro-modules` `^0.35.0 || ^0.36.0`
+
+On iOS, install pods after adding the package:
+
+```bash
+cd ios && pod install
+```
+
+## Usage
+
+```ts
+import { reverseGeocode } from '@inoxialabs/react-native-nitro-location-geocoder';
+
+const result = await reverseGeocode(-12.0464, -77.0428, 'es-PE');
+
+console.log(result.countryCode);
+console.log(result.country);
+console.log(result.locality);
+console.log(result.administrativeArea);
+```
+
+To use the system default locale, pass an empty string:
+
+```ts
+const result = await reverseGeocode(4.711, -74.0721, '');
+```
+
+## API
+
+### `reverseGeocode(latitude, longitude, locale)`
+
+Returns `Promise<LocationGeocoderResult>`.
+
+Parameters:
+
+- `latitude`: required `number`
+- `longitude`: required `number`
+- `locale`: required `string`
+
+`locale` accepts a language tag such as `en`, `es`, or `es-PE`. Passing `''` uses the platform default locale, but the argument itself is still required.
+Latitude must be finite and between `-90` and `90`. Longitude must be finite and between `-180` and `180`.
+
+### `LocationGeocoderResult`
+
+```ts
+type LocationGeocoderResult = {
+  countryCode: string;
+  country: string;
+  locality: string;
+  administrativeArea: string;
+  subAdministrativeArea: string;
+  subLocality: string;
+};
+```
+
+All fields are always present. When the platform geocoder cannot provide a field, the module returns an empty string for that property.
+
+## Platform behavior
+
+- iOS uses `CLGeocoder`.
+- Android uses `android.location.Geocoder`.
+- Calls are independent. Starting one reverse-geocode request does not cancel another request.
+- Requests time out after 10 seconds with `GEOCODER_TIMEOUT`.
+- The module rejects with `INVALID_COORDINATES` when latitude or longitude is outside the valid coordinate range.
+- The module rejects with `NO_RESULTS` when no address is found.
+- Android rejects with `UNAVAILABLE` when the platform geocoder is not available.
+- iOS wraps native geocoder failures as `GEOCODER_FAILED: <platform message>`.
+- Android wraps native geocoder failures as `GEOCODER_FAILED` or `GEOCODER_FAILED: <platform message>`.
+
+## Notes
+
+- The module reverse geocodes coordinates that you already have. It does not request GPS updates or device location permissions.
+- The package exports `reverseGeocode`, `Geocoder`, and the default `Geocoder` object.
+
+## Development
+
+Regenerate Nitro bindings after changing `src/specs/LocationGeocoder.nitro.ts` or `nitro.json`:
+
+```bash
+npm install
+npm run specs
+npm test
+```
+
+Validate the published package contents:
+
+```bash
+npm pack --dry-run
+```

package/android/CMakeLists.txt

@@ -1,25 +1,25 @@
-project(NitroLocationGeocoder)
-cmake_minimum_required(VERSION 3.9.0)
-
-set(PACKAGE_NAME NitroLocationGeocoder)
-set(CMAKE_VERBOSE_MAKEFILE ON)
-set(CMAKE_CXX_STANDARD 20)
-
-add_library(${PACKAGE_NAME} SHARED
-  src/main/cpp/cpp-adapter.cpp
-)
-
-include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroLocationGeocoder+autolinking.cmake)
-
-include_directories(
-  "src/main/cpp"
-  "../cpp"
-)
-
-find_library(LOG_LIB log)
-
-target_link_libraries(
-  ${PACKAGE_NAME}
-  ${LOG_LIB}
-  android
-)
+project(NitroLocationGeocoder)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME NitroLocationGeocoder)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+add_library(${PACKAGE_NAME} SHARED
+  src/main/cpp/cpp-adapter.cpp
+)
+
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroLocationGeocoder+autolinking.cmake)
+
+include_directories(
+  "src/main/cpp"
+  "../cpp"
+)
+
+find_library(LOG_LIB log)
+
+target_link_libraries(
+  ${PACKAGE_NAME}
+  ${LOG_LIB}
+  android
+)

package/android/build.gradle

@@ -1,129 +1,129 @@
-buildscript {
-  repositories {
-    google()
-    mavenCentral()
-  }
-
-  dependencies {
-    classpath "com.android.tools.build:gradle:8.13.1"
-  }
-}
-
-def reactNativeArchitectures() {
-  def value = rootProject.getProperties().get("reactNativeArchitectures")
-  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
-}
-
-def isNewArchitectureEnabled() {
-  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
-}
-
-apply plugin: "com.android.library"
-apply plugin: "org.jetbrains.kotlin.android"
-apply from: "../nitrogen/generated/android/NitroLocationGeocoder+autolinking.gradle"
-apply from: "./fix-prefab.gradle"
-
-if (isNewArchitectureEnabled()) {
-  apply plugin: "com.facebook.react"
-}
-
-def getExtOrDefault(name) {
-  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroLocationGeocoder_" + name]
-}
-
-def getExtOrIntegerDefault(name) {
-  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroLocationGeocoder_" + name]).toInteger()
-}
-
-android {
-  namespace "com.margelo.nitro.locationgeocoder"
-
-  ndkVersion getExtOrDefault("ndkVersion")
-  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
-
-  defaultConfig {
-    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
-    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
-    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
-
-    externalNativeBuild {
-      cmake {
-        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
-        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
-        abiFilters (*reactNativeArchitectures())
-
-        buildTypes {
-          debug {
-            cppFlags "-O1 -g"
-          }
-          release {
-            cppFlags "-O2"
-          }
-        }
-      }
-    }
-  }
-
-  externalNativeBuild {
-    cmake {
-      path "CMakeLists.txt"
-    }
-  }
-
-  packagingOptions {
-    excludes = [
-      "META-INF",
-      "META-INF/**",
-      "**/libc++_shared.so",
-      "**/libfbjni.so",
-      "**/libjsi.so",
-      "**/libfolly_json.so",
-      "**/libfolly_runtime.so",
-      "**/libglog.so",
-      "**/libhermes.so",
-      "**/libhermes-executor-debug.so",
-      "**/libhermes_executor.so",
-      "**/libreactnative.so",
-      "**/libreactnativejni.so",
-      "**/libturbomodulejsijni.so",
-      "**/libreact_nativemodule_core.so",
-      "**/libjscexecutor.so"
-    ]
-  }
-
-  buildFeatures {
-    buildConfig true
-    prefab true
-  }
-
-  buildTypes {
-    release {
-      minifyEnabled false
-    }
-  }
-
-  compileOptions {
-    sourceCompatibility JavaVersion.VERSION_1_8
-    targetCompatibility JavaVersion.VERSION_1_8
-  }
-
-  sourceSets {
-    main {
-      if (isNewArchitectureEnabled()) {
-        java.srcDirs += [
-          "${project.buildDir}/generated/source/codegen/java"
-        ]
-      }
-    }
-  }
-}
-
-repositories {
-  mavenCentral()
-  google()
-}
-
-dependencies {
-  implementation "com.facebook.react:react-native:+"
-  implementation project(":react-native-nitro-modules")
-}
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.13.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply from: "../nitrogen/generated/android/NitroLocationGeocoder+autolinking.gradle"
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroLocationGeocoder_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroLocationGeocoder_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.locationgeocoder"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-native:+"
+  implementation project(":react-native-nitro-modules")
+}

package/android/fix-prefab.gradle

@@ -1,44 +1,44 @@
-tasks.configureEach { task ->
-  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
-  def matcher = task.name =~ prefabConfigurePattern
-  if (matcher.matches()) {
-    def variantName = matcher[0][1]
-    task.outputs.upToDateWhen { false }
-    task.dependsOn("externalNativeBuild${variantName}")
-  }
-}
-
-afterEvaluate {
-  def abis = reactNativeArchitectures()
-  rootProject.allprojects.each { proj ->
-    if (proj === rootProject) return
-
-    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
-      config.dependencies.any { dep ->
-        dep.group == project.group && dep.name == project.name
-      }
-    }
-    if (!dependsOnThisLib && proj != project) return
-
-    if (!proj.plugins.hasPlugin("com.android.application") && !proj.plugins.hasPlugin("com.android.library")) {
-      return
-    }
-
-    def variants = proj.android.hasProperty("applicationVariants") ? proj.android.applicationVariants : proj.android.libraryVariants
-    variants.all { variant ->
-      def variantName = variant.name
-      abis.each { abi ->
-        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
-        if (!searchDir.exists()) return
-        def matches = []
-        searchDir.eachDir { randomDir ->
-          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
-          if (prefabFile.exists()) matches << prefabFile
-        }
-        matches.each { prefabConfig ->
-          prefabConfig.setLastModified(System.currentTimeMillis())
-        }
-      }
-    }
-  }
-}
+tasks.configureEach { task ->
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin("com.android.application") && !proj.plugins.hasPlugin("com.android.library")) {
+      return
+    }
+
+    def variants = proj.android.hasProperty("applicationVariants") ? proj.android.applicationVariants : proj.android.libraryVariants
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -1,5 +1,5 @@
-NitroLocationGeocoder_kotlinVersion=2.1.20
-NitroLocationGeocoder_minSdkVersion=24
-NitroLocationGeocoder_targetSdkVersion=36
-NitroLocationGeocoder_compileSdkVersion=36
-NitroLocationGeocoder_ndkVersion=27.1.12297006
+NitroLocationGeocoder_kotlinVersion=2.1.20
+NitroLocationGeocoder_minSdkVersion=24
+NitroLocationGeocoder_targetSdkVersion=36
+NitroLocationGeocoder_compileSdkVersion=36
+NitroLocationGeocoder_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,2 @@
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-  package="com.margelo.nitro.locationgeocoder" />
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.margelo.nitro.locationgeocoder" />