use-geo-sync 1.0.0 → 1.0.2

package/dist/index.d.mts

@@ -5,6 +5,7 @@ interface GeoPoint {
     timestamp: number;
     accuracy: number | null;
     speed: number | null;
+    heading: number | null;
 }
 interface SyncConfig {
     batchSize?: number;
@@ -31,5 +32,6 @@ declare function useGeoPermissions(): {
 declare function useGeoSync(config?: SyncConfig): UseGeoSyncResult;
 
 declare const BACKGROUND_LOCATION_TASK = "BACKGROUND_LOCATION_TASK";
+declare let locationQueue: GeoPoint[];
 
-export { BACKGROUND_LOCATION_TASK, type GeoPoint, type PermissionState, type SyncConfig, type UseGeoSyncResult, useGeoPermissions, useGeoSync };
+export { BACKGROUND_LOCATION_TASK, type GeoPoint, type PermissionState, type SyncConfig, type UseGeoSyncResult, locationQueue, useGeoPermissions, useGeoSync };

package/dist/index.d.ts

@@ -5,6 +5,7 @@ interface GeoPoint {
     timestamp: number;
     accuracy: number | null;
     speed: number | null;
+    heading: number | null;
 }
 interface SyncConfig {
     batchSize?: number;
@@ -31,5 +32,6 @@ declare function useGeoPermissions(): {
 declare function useGeoSync(config?: SyncConfig): UseGeoSyncResult;
 
 declare const BACKGROUND_LOCATION_TASK = "BACKGROUND_LOCATION_TASK";
+declare let locationQueue: GeoPoint[];
 
-export { BACKGROUND_LOCATION_TASK, type GeoPoint, type PermissionState, type SyncConfig, type UseGeoSyncResult, useGeoPermissions, useGeoSync };
+export { BACKGROUND_LOCATION_TASK, type GeoPoint, type PermissionState, type SyncConfig, type UseGeoSyncResult, locationQueue, useGeoPermissions, useGeoSync };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BACKGROUND_LOCATION_TASK: () => BACKGROUND_LOCATION_TASK,
+  locationQueue: () => locationQueue,
   useGeoPermissions: () => useGeoPermissions,
   useGeoSync: () => useGeoSync
 });
@@ -111,7 +112,9 @@ TaskManager.defineTask(BACKGROUND_LOCATION_TASK, async ({ data, error }) => {
       longitude: loc.coords.longitude,
       timestamp: loc.timestamp,
       accuracy: loc.coords.accuracy,
-      speed: loc.coords.speed
+      speed: loc.coords.speed,
+      heading: loc.coords.heading
+      // <-- ADD THIS NEW LINE
     }));
     locationQueue.push(...newPoints);
     console.log(`[use-geo-sync] \u{1F4CD} Caught ${newPoints.length} points. Queue size: ${locationQueue.length}`);
@@ -194,6 +197,7 @@ function useGeoSync(config) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BACKGROUND_LOCATION_TASK,
+  locationQueue,
   useGeoPermissions,
   useGeoSync
 });

package/dist/index.mjs

@@ -73,7 +73,9 @@ TaskManager.defineTask(BACKGROUND_LOCATION_TASK, async ({ data, error }) => {
       longitude: loc.coords.longitude,
       timestamp: loc.timestamp,
       accuracy: loc.coords.accuracy,
-      speed: loc.coords.speed
+      speed: loc.coords.speed,
+      heading: loc.coords.heading
+      // <-- ADD THIS NEW LINE
     }));
     locationQueue.push(...newPoints);
     console.log(`[use-geo-sync] \u{1F4CD} Caught ${newPoints.length} points. Queue size: ${locationQueue.length}`);
@@ -155,6 +157,7 @@ function useGeoSync(config) {
 }
 export {
   BACKGROUND_LOCATION_TASK,
+  locationQueue,
   useGeoPermissions,
   useGeoSync
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-geo-sync",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A React Native/Expo headless toolkit for background location sync and queuing.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/readme.md

@@ -1,4 +1,4 @@
-Markdown# use-geo-sync 🌍
+# use-geo-sync 🌍
 
 A plug-and-play, offline-first background location tracking and syncing toolkit for React Native and Expo. 
 
@@ -8,7 +8,7 @@ Handling iOS/Android background permissions, app state, and network drops is a m
 - **📱 Bulletproof Permissions:** Automatically handles the strict Foreground -> Background permission cascade on both iOS and Android.
 - **🔋 Battery Optimized:** Uses balanced accuracy and headless task management to save battery life.
 - **📡 Offline-First Queuing:** If the network drops, coordinates are safely queued locally. When the connection returns, the queue is automatically batched and synced to your backend.
-- **🛠 Zero-Config Architecture:** No complex Redux/Zustand setups required. It just works.
+- **🧭 Live Navigation Ready:** Exposes compass headings and the raw local queue to build Uber-style live map arrows.
 
 ## 📦 Installation
 
@@ -23,62 +23,95 @@ Important: This package relies on Expo modules under the hood. You must install
 npx expo install expo-location expo-task-manager
 ```
 
-# 🚀 Quick Start
-Here is a complete example of how to implement background tracking in your app:
+# 🚀 Standard API Sync (Quick Start)
+Here is how to set up automatic background tracking that syncs to your database in batches:
 ```
-import { useEffect } from 'react';
-import { View, Text, Button, StyleSheet } from 'react-native';
+import { View, Text, Button } from 'react-native';
 import { useGeoSync } from 'use-geo-sync';
 
 export default function TrackingScreen() {
-  const { 
-    permissionState, 
-    requestPermissions, 
-    startTracking, 
-    stopTracking, 
-    isTracking, 
-    queueLength 
-  } = useGeoSync({
-    syncEndpoint: '[https://your-api.com/api/location-sync](https://your-api.com/api/location-sync)', // Your backend URL
-    batchSize: 20, // Auto-syncs to your backend after collecting 20 points
-    syncIntervalMs: 10000 // Pings GPS every 10 seconds
+  const { permissionState, requestPermissions, startTracking, stopTracking, isTracking } = useGeoSync({
+    syncEndpoint: '[https://your-api.com/api/location-sync](https://your-api.com/api/location-sync)', 
+    batchSize: 20, 
   });
 
   return (
-    <View style={styles.container}>
-      <Text style={styles.title}>📍 Fleet Tracker</Text>
-      
-      <Text>Status: {isTracking ? 'Active 🟢' : 'Stopped 🔴'}</Text>
+    <View>
       <Text>Permissions: {permissionState}</Text>
-      <Text>Unsynced Points in Queue: {queueLength}</Text>
-
       {permissionState !== 'granted_background' && (
-        <Button title="Grant Background Permissions" onPress={requestPermissions} />
+        <Button title="Grant Permissions" onPress={requestPermissions} />
       )}
-
       <Button 
-        title={isTracking ? "Stop Tracking" : "Start Tracking"} 
+        title={isTracking ? "Stop" : "Start"} 
         onPress={isTracking ? stopTracking : startTracking} 
-        color={isTracking ? "red" : "green"}
       />
     </View>
   );
 }
+```
+
+## 🗺️ Advanced Use Cases (Offline & Maps)
+
+If you don't provide a `syncEndpoint`, the package acts as a powerful local GPS engine. You can import the raw `locationQueue` to build complex map features.
+
+### 1. The Uber-Style Live Navigation Arrow
+Keep a map marker perfectly locked onto the user's position and rotation, even if the app goes into the background.
+
+```
+import { useEffect, useState } from 'react';
+import MapView, { Marker } from 'react-native-maps';
+import { useGeoSync, locationQueue } from 'use-geo-sync';
+
+export default function LiveMap() {
+  const { queueLength } = useGeoSync({ batchSize: 1000 }); // High batch size for local use
+  const [currentLoc, setCurrentLoc] = useState(null);
+
+  useEffect(() => {
+    if (queueLength > 0) {
+      setCurrentLoc(locationQueue[locationQueue.length - 1]);
+    }
+  }, [queueLength]);
+
+  return (
+    <MapView style={{ flex: 1 }}>
+      {currentLoc && (
+        <Marker
+          coordinate={{ latitude: currentLoc.latitude, longitude: currentLoc.longitude }}
+          // Rotate the custom arrow image based on user's compass heading
+          style={{ transform: [{ rotate: `${currentLoc.heading || 0}deg` }] }}
+          image={require('./assets/arrow.png')} 
+        />
+      )}
+    </MapView>
+  );
+}
+```
+
+### 2. Offline Breadcrumb Trails
+Draw a line of exactly where the user has walked today, entirely offline.
 
-const styles = StyleSheet.create({
-  container: { flex: 1, justifyContent: 'center', alignItems: 'center', gap: 10 },
-  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 }
-});
 ```
+import MapView, { Polyline } from 'react-native-maps';
+import { useGeoSync, locationQueue } from 'use-geo-sync';
 
+export function MapScreen() {
+  const { isTracking } = useGeoSync({ batchSize: 1000 }); 
+
+  return (
+    <MapView style={{ flex: 1 }}>
+      <Polyline coordinates={locationQueue} strokeColor="#000" strokeWidth={4} />
+    </MapView>
+  );
+}
+```
 ## ⚙️ Configuration Options (SyncConfig)
 
 When calling `useGeoSync(config)`, you can pass the following options:
 
 | Property | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `syncEndpoint` | `string` | `undefined` | The backend API URL where the queued location batch will be sent via POST request. |
-| `batchSize` | `number` | `20` | How many location points to collect before triggering a sync to the backend. |
+| `syncEndpoint` | `string` | `undefined` | The backend API URL to POST batched coordinates to. |
+| `batchSize` | `number` | `20` | How many location points to collect before syncing. |
 | `syncIntervalMs` | `number` | `10000` | Time in milliseconds between GPS pings. |
 
 ## 📜 License

package/src/backgroundTask.ts

@@ -27,13 +27,14 @@ TaskManager.defineTask(BACKGROUND_LOCATION_TASK, async ({ data, error }) => {
     const { locations } = data as { locations: Location.LocationObject[] };
     
     // 1. Transform Expo's object
-    const newPoints: GeoPoint[] = locations.map(loc => ({
+const newPoints: GeoPoint[] = locations.map(loc => ({
       id: `${loc.timestamp}-${Math.random().toString(36).substr(2, 9)}`,
       latitude: loc.coords.latitude,
       longitude: loc.coords.longitude,
       timestamp: loc.timestamp,
       accuracy: loc.coords.accuracy,
-      speed: loc.coords.speed
+      speed: loc.coords.speed,
+      heading: loc.coords.heading // <-- ADD THIS NEW LINE
     }));
 
     // 2. Add to Queue

package/src/index.ts

@@ -3,4 +3,4 @@
 export * from './types';
 export { useGeoPermissions } from './useGeoPermissions';
 export { useGeoSync } from './useGeoSync';
-export { BACKGROUND_LOCATION_TASK } from './backgroundTask';
+export { BACKGROUND_LOCATION_TASK, locationQueue } from './backgroundTask'; // <-- ADD locationQueue

package/src/types.ts

@@ -3,19 +3,20 @@
 import * as Location from 'expo-location';
 
 export interface GeoPoint {
-  id: string; // Unique ID for the queue
+  id: string; 
   latitude: number;
   longitude: number;
   timestamp: number;
   accuracy: number | null;
   speed: number | null;
+  heading: number | null; // <-- ADD THIS NEW LINE
 }
 
 export interface SyncConfig {
-  batchSize?: number; // How many points to hold before syncing (default: 20)
-  syncEndpoint?: string; // The backend URL to POST data to
-  syncIntervalMs?: number; // Time-based sync fallback
-  retryLimit?: number; // How many times to retry a failed sync
+  batchSize?: number; 
+  syncEndpoint?: string; 
+  syncIntervalMs?: number; 
+  retryLimit?: number; 
 }
 
 export type PermissionState = 
@@ -31,5 +32,5 @@ export interface UseGeoSyncResult {
   startTracking: () => Promise<void>;
   stopTracking: () => Promise<void>;
   isTracking: boolean;
-  queueLength: number; // Number of unsynced points
+  queueLength: number; 
 }