@kafitra/react-native-live-tracking 0.1.0

package/lib/commonjs/serialization/locationSerializer.js

@@ -0,0 +1,51 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.serializeLocationForTarget = serializeLocationForTarget;
+/**
+ * Location serialization for Firebase sync targets.
+ *
+ * Transforms LocationData into a generic payload suitable for any
+ * sync target, regardless of write method (set, push, update).
+ *
+ * @packageDocumentation
+ */
+
+// ─── Payload Interface ───────────────────────────────────────────────────────
+
+/**
+ * Serialized location payload for any sync target.
+ *
+ * Contains required fields (latitude, longitude, timestamp, accuracy)
+ * and optional sensor fields (speed, heading, altitude) which are
+ * included as `null` when unavailable from the device sensor.
+ * Placeholder values (0, -1) are never used for unavailable fields.
+ */
+
+// ─── Serialization Function ──────────────────────────────────────────────────
+
+/**
+ * Serialize a LocationData object for a generic Firebase sync target.
+ *
+ * Produces a payload containing all required location fields and optional
+ * sensor fields. When optional fields (speed, heading/bearing, altitude)
+ * are unavailable from the device sensor, they are included as `null`.
+ * Default placeholder values (0, -1) are never written for unavailable fields.
+ *
+ * @param location - The location data to serialize
+ * @returns Serialized payload for the sync target
+ */
+function serializeLocationForTarget(location) {
+  return {
+    latitude: location.latitude,
+    longitude: location.longitude,
+    timestamp: location.timestamp,
+    accuracy: location.accuracy,
+    speed: location.speed,
+    heading: location.bearing,
+    altitude: location.altitude
+  };
+}
+//# sourceMappingURL=locationSerializer.js.map

package/lib/commonjs/serialization/locationSerializer.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["serializeLocationForTarget","location","latitude","longitude","timestamp","accuracy","speed","heading","bearing","altitude"],"sourceRoot":"../../../src","sources":["serialization/locationSerializer.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAWA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,0BAA0BA,CACxCC,QAAsB,EACC;EACvB,OAAO;IACLC,QAAQ,EAAED,QAAQ,CAACC,QAAQ;IAC3BC,SAAS,EAAEF,QAAQ,CAACE,SAAS;IAC7BC,SAAS,EAAEH,QAAQ,CAACG,SAAS;IAC7BC,QAAQ,EAAEJ,QAAQ,CAACI,QAAQ;IAC3BC,KAAK,EAAEL,QAAQ,CAACK,KAAK;IACrBC,OAAO,EAAEN,QAAQ,CAACO,OAAO;IACzBC,QAAQ,EAAER,QAAQ,CAACQ;EACrB,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/types.js

@@ -0,0 +1,77 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TrackingState = void 0;
+/**
+ * TypeScript type definitions for react-native-live-tracking.
+ *
+ * @packageDocumentation
+ */
+// ─── Enums ───────────────────────────────────────────────────────────────────
+/**
+ * Internal state machine for tracking lifecycle.
+ */
+let TrackingState = exports.TrackingState = /*#__PURE__*/function (TrackingState) {
+  TrackingState["IDLE"] = "idle";
+  TrackingState["CONFIGURED"] = "configured";
+  TrackingState["TRACKING"] = "tracking";
+  TrackingState["MOTION_SLEEP"] = "motion_sleep";
+  TrackingState["PAUSED_GPS"] = "paused_gps";
+  return TrackingState;
+}({}); // ─── Configuration Interfaces ────────────────────────────────────────────────
+/**
+ * Strategy used by the distance/time filter.
+ * - 'interval': accept when enough time has elapsed
+ * - 'distance': accept when enough distance has been covered
+ * - 'both': accept only when both conditions are met (default)
+ */
+/**
+ * Optimization parameters for location tracking.
+ */
+/**
+ * Android foreground service notification configuration.
+ */
+/**
+ * iOS persistent notification configuration.
+ * Shows a local notification while tracking is active (similar to Android's foreground service notification).
+ */
+/**
+ * A user-defined sync target specifying a Firebase path, write method,
+ * and optional batching/offline queue settings.
+ */
+/**
+ * Firebase connection and sync target configuration.
+ */
+/**
+ * Main configuration object passed to `configure()`.
+ */
+// ─── Data Interfaces ─────────────────────────────────────────────────────────
+/**
+ * Location data emitted by the library on each valid location update.
+ */
+// ─── Error & Status Interfaces ───────────────────────────────────────────────
+/**
+ * Error object emitted by the library when tracking issues occur.
+ */
+/**
+ * Current tracking status snapshot.
+ */
+// ─── Validation Interfaces ───────────────────────────────────────────────────
+/**
+ * Single configuration validation error.
+ */
+/**
+ * Result of configuration validation.
+ */
+// ─── Utility Types ───────────────────────────────────────────────────────────
+/**
+ * Subscription handle returned by event listener registrations.
+ * Call `remove()` to unsubscribe from the event.
+ */
+// ─── Module Interface ────────────────────────────────────────────────────────
+/**
+ * Main public API interface for the react-native-live-tracking library.
+ */
+//# sourceMappingURL=types.js.map

package/lib/commonjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TrackingState","exports"],"sourceRoot":"../../src","sources":["types.ts"],"mappings":";;;;;;AAAA;AACA;AACA;AACA;AACA;AAEA;AAEA;AACA;AACA;AAFA,IAGYA,aAAa,GAAAC,OAAA,CAAAD,aAAA,0BAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAA,OAAbA,aAAa;AAAA,OAQzB;AAEA;AACA;AACA;AACA;AACA;AACA;AAGA;AACA;AACA;AAYA;AACA;AACA;AAgBA;AACA;AACA;AACA;AAUA;AACA;AACA;AACA;AAYA;AACA;AACA;AAQA;AACA;AACA;AAYA;AAEA;AACA;AACA;AAkBA;AAEA;AACA;AACA;AAYA;AACA;AACA;AAcA;AAEA;AACA;AACA;AAUA;AACA;AACA;AAQA;AAEA;AACA;AACA;AACA;AAMA;AAEA;AACA;AACA","ignoreList":[]}

package/lib/commonjs/utils/distance.js

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.EARTH_RADIUS_METERS = void 0;
+exports.calculateDistance = calculateDistance;
+/**
+ * Distance calculation utility using the Haversine formula.
+ *
+ * The Haversine formula determines the great-circle distance between two points
+ * on a sphere given their longitudes and latitudes. This is used by the
+ * Distance/Time Matrix filter to determine if a new location update has moved
+ * far enough from the last known position.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Earth's mean radius in meters.
+ * Used as the sphere radius in the Haversine formula.
+ */
+const EARTH_RADIUS_METERS = exports.EARTH_RADIUS_METERS = 6371000;
+
+/**
+ * Converts degrees to radians.
+ *
+ * @param degrees - Angle in degrees
+ * @returns Angle in radians
+ */
+function toRadians(degrees) {
+  return degrees * (Math.PI / 180);
+}
+
+/**
+ * Calculates the distance in meters between two geographic coordinates
+ * using the Haversine formula.
+ *
+ * The Haversine formula accounts for the curvature of the Earth and provides
+ * accurate results for short and medium distances. It assumes a spherical Earth
+ * with a mean radius of 6,371,000 meters.
+ *
+ * @param lat1 - Latitude of the first point in degrees (-90 to 90)
+ * @param lng1 - Longitude of the first point in degrees (-180 to 180)
+ * @param lat2 - Latitude of the second point in degrees (-90 to 90)
+ * @param lng2 - Longitude of the second point in degrees (-180 to 180)
+ * @returns Distance between the two points in meters
+ *
+ * @example
+ * ```typescript
+ * // Distance between Jakarta and Bandung (approximately 120 km)
+ * const distance = calculateDistance(-6.2088, 106.8456, -6.9175, 107.6191);
+ * console.log(distance); // ~120,000 meters
+ * ```
+ */
+function calculateDistance(lat1, lng1, lat2, lng2) {
+  const dLat = toRadians(lat2 - lat1);
+  const dLng = toRadians(lng2 - lng1);
+  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.cos(toRadians(lat1)) * Math.cos(toRadians(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return EARTH_RADIUS_METERS * c;
+}
+//# sourceMappingURL=distance.js.map

package/lib/commonjs/utils/distance.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["EARTH_RADIUS_METERS","exports","toRadians","degrees","Math","PI","calculateDistance","lat1","lng1","lat2","lng2","dLat","dLng","a","sin","cos","c","atan2","sqrt"],"sourceRoot":"../../../src","sources":["utils/distance.ts"],"mappings":";;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA;AACA;AACA;AACO,MAAMA,mBAAmB,GAAAC,OAAA,CAAAD,mBAAA,GAAG,OAAO;;AAE1C;AACA;AACA;AACA;AACA;AACA;AACA,SAASE,SAASA,CAACC,OAAe,EAAU;EAC1C,OAAOA,OAAO,IAAIC,IAAI,CAACC,EAAE,GAAG,GAAG,CAAC;AAClC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAC/BC,IAAY,EACZC,IAAY,EACZC,IAAY,EACZC,IAAY,EACJ;EACR,MAAMC,IAAI,GAAGT,SAAS,CAACO,IAAI,GAAGF,IAAI,CAAC;EACnC,MAAMK,IAAI,GAAGV,SAAS,CAACQ,IAAI,GAAGF,IAAI,CAAC;EAEnC,MAAMK,CAAC,GACLT,IAAI,CAACU,GAAG,CAACH,IAAI,GAAG,CAAC,CAAC,GAAGP,IAAI,CAACU,GAAG,CAACH,IAAI,GAAG,CAAC,CAAC,GACvCP,IAAI,CAACW,GAAG,CAACb,SAAS,CAACK,IAAI,CAAC,CAAC,GACvBH,IAAI,CAACW,GAAG,CAACb,SAAS,CAACO,IAAI,CAAC,CAAC,GACzBL,IAAI,CAACU,GAAG,CAACF,IAAI,GAAG,CAAC,CAAC,GAClBR,IAAI,CAACU,GAAG,CAACF,IAAI,GAAG,CAAC,CAAC;EAEtB,MAAMI,CAAC,GAAG,CAAC,GAAGZ,IAAI,CAACa,KAAK,CAACb,IAAI,CAACc,IAAI,CAACL,CAAC,CAAC,EAAET,IAAI,CAACc,IAAI,CAAC,CAAC,GAAGL,CAAC,CAAC,CAAC;EAExD,OAAOb,mBAAmB,GAAGgB,CAAC;AAChC","ignoreList":[]}

package/lib/commonjs/utils/retry.js

@@ -0,0 +1,80 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MAX_RETRIES_SET_UPDATE = exports.MAX_RETRIES_PUSH = exports.DEFAULT_MAX_JITTER = exports.DEFAULT_BASE_DELAY = void 0;
+exports.calculateBackoffDelay = calculateBackoffDelay;
+exports.shouldRetry = shouldRetry;
+/**
+ * Exponential backoff retry utilities for Firebase write operations.
+ *
+ * Used by the Firebase Sync Engine to determine delay between retry attempts
+ * when writes fail due to network issues or transient errors.
+ *
+ * @module utils/retry
+ */
+
+/** Default base delay in milliseconds for exponential backoff */
+const DEFAULT_BASE_DELAY = exports.DEFAULT_BASE_DELAY = 1000;
+
+/** Default maximum jitter in milliseconds (±) to avoid thundering herd */
+const DEFAULT_MAX_JITTER = exports.DEFAULT_MAX_JITTER = 200;
+
+/** Maximum retry attempts for sync targets using 'set' or 'update' write methods */
+const MAX_RETRIES_SET_UPDATE = exports.MAX_RETRIES_SET_UPDATE = 3;
+
+/** Maximum retry attempts for sync targets using 'push' write method */
+const MAX_RETRIES_PUSH = exports.MAX_RETRIES_PUSH = 5;
+
+/**
+ * Calculates the delay before the next retry attempt using exponential backoff
+ * with random jitter.
+ *
+ * Formula: delay = baseDelay × 2^(attempt - 1) + random(-maxJitter, +maxJitter)
+ *
+ * The result is clamped to a minimum of 0 to prevent negative delays.
+ *
+ * @param attempt - The retry attempt number (1-indexed, first retry = 1)
+ * @param baseDelay - The base delay in milliseconds (default: 1000ms)
+ * @param maxJitter - The maximum jitter offset in milliseconds (default: 200ms).
+ *   A random value between -maxJitter and +maxJitter is added to the delay.
+ * @returns The calculated delay in milliseconds (never negative)
+ *
+ * @example
+ * ```typescript
+ * // First retry: ~1000ms ± 200ms
+ * const delay1 = calculateBackoffDelay(1);
+ *
+ * // Second retry: ~2000ms ± 200ms
+ * const delay2 = calculateBackoffDelay(2);
+ *
+ * // Third retry: ~4000ms ± 200ms
+ * const delay3 = calculateBackoffDelay(3);
+ * ```
+ */
+function calculateBackoffDelay(attempt, baseDelay = DEFAULT_BASE_DELAY, maxJitter = DEFAULT_MAX_JITTER) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt - 1);
+  const jitter = (Math.random() * 2 - 1) * maxJitter;
+  return Math.max(0, exponentialDelay + jitter);
+}
+
+/**
+ * Determines whether a retry should be attempted based on the current attempt
+ * number and the maximum allowed retries.
+ *
+ * @param attempt - The current attempt number (1-indexed)
+ * @param maxRetries - The maximum number of retries allowed
+ * @returns `true` if the attempt is within the allowed retry limit, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * shouldRetry(1, 3); // true - first retry is allowed
+ * shouldRetry(3, 3); // true - third retry is allowed
+ * shouldRetry(4, 3); // false - exceeds max retries
+ * ```
+ */
+function shouldRetry(attempt, maxRetries) {
+  return attempt <= maxRetries;
+}
+//# sourceMappingURL=retry.js.map

package/lib/commonjs/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_BASE_DELAY","exports","DEFAULT_MAX_JITTER","MAX_RETRIES_SET_UPDATE","MAX_RETRIES_PUSH","calculateBackoffDelay","attempt","baseDelay","maxJitter","exponentialDelay","Math","pow","jitter","random","max","shouldRetry","maxRetries"],"sourceRoot":"../../../src","sources":["utils/retry.ts"],"mappings":";;;;;;;;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACO,MAAMA,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,GAAG,IAAI;;AAEtC;AACO,MAAME,kBAAkB,GAAAD,OAAA,CAAAC,kBAAA,GAAG,GAAG;;AAErC;AACO,MAAMC,sBAAsB,GAAAF,OAAA,CAAAE,sBAAA,GAAG,CAAC;;AAEvC;AACO,MAAMC,gBAAgB,GAAAH,OAAA,CAAAG,gBAAA,GAAG,CAAC;;AAEjC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,qBAAqBA,CACnCC,OAAe,EACfC,SAAiB,GAAGP,kBAAkB,EACtCQ,SAAiB,GAAGN,kBAAkB,EAC9B;EACR,MAAMO,gBAAgB,GAAGF,SAAS,GAAGG,IAAI,CAACC,GAAG,CAAC,CAAC,EAAEL,OAAO,GAAG,CAAC,CAAC;EAC7D,MAAMM,MAAM,GAAG,CAACF,IAAI,CAACG,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAIL,SAAS;EAClD,OAAOE,IAAI,CAACI,GAAG,CAAC,CAAC,EAAEL,gBAAgB,GAAGG,MAAM,CAAC;AAC/C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,WAAWA,CAACT,OAAe,EAAEU,UAAkB,EAAW;EACxE,OAAOV,OAAO,IAAIU,UAAU;AAC9B","ignoreList":[]}