@kafitra/react-native-live-tracking 0.1.0

package/lib/module/LiveTracking.js

@@ -0,0 +1,127 @@
+/**
+ * JavaScript LiveTracking module that wraps NativeModule calls.
+ *
+ * Provides the public API for configuring, starting, and stopping
+ * location tracking, with validation and state management.
+ *
+ * @packageDocumentation
+ */
+
+import NativeLiveTracking from './NativeLiveTracking';
+import { onLocationUpdate as emitterOnLocationUpdate, onError as emitterOnError } from './EventEmitter';
+import { validateConfig, applyDefaults } from './validation';
+
+/**
+ * Returns the native module or throws a descriptive error if not linked.
+ * Using a function accessor (rather than assertNative) keeps TypeScript
+ * happy since it can't narrow an imported binding via assertion functions.
+ */
+function native() {
+  if (!NativeLiveTracking) {
+    throw new Error("[@kafitra/react-native-live-tracking] Native module 'LiveTracking' is not registered. " + 'Make sure you ran `pod install` and rebuilt the app from Xcode.');
+  }
+  return NativeLiveTracking;
+}
+
+/**
+ * Tracks whether configure() has been successfully called.
+ * Used to guard queue methods that require configuration.
+ */
+let isConfigured = false;
+
+/**
+ * Resets the configured state. Only for use in tests.
+ * @internal
+ */
+export function _resetConfiguredStateForTesting() {
+  isConfigured = false;
+}
+
+/**
+ * LiveTracking module implementation.
+ *
+ * Wraps native module calls with validation, serialization,
+ * and state management on the JavaScript side.
+ */
+const LiveTracking = {
+  /**
+   * Configure the tracking library with the given parameters.
+   * Validates the config, applies defaults, and passes to native layer.
+   */
+  async configure(config) {
+    const validationResult = validateConfig(config);
+    if (!validationResult.valid) {
+      const errorMessages = validationResult.errors.map(e => `[${e.field}]: ${e.message}`).join('; ');
+      throw new Error(`Invalid configuration: ${errorMessages}`);
+    }
+    const finalConfig = applyDefaults(config);
+    const jsonString = JSON.stringify(finalConfig);
+    const MAX_PAYLOAD_BYTES = 1024 * 1024; // 1 MB
+    if (jsonString.length > MAX_PAYLOAD_BYTES) {
+      throw new Error('Configuration payload is too large: serialized JSON exceeds 1 MB');
+    }
+    await native().configure(jsonString);
+    isConfigured = true;
+  },
+  /**
+   * Start location tracking.
+   * Requires `configure()` to have been called first.
+   */
+  async start() {
+    await native().start();
+  },
+  /**
+   * Stop location tracking and clean up resources.
+   */
+  async stop() {
+    await native().stop();
+  },
+  /**
+   * Register a callback for location updates.
+   */
+  onLocationUpdate(callback) {
+    return emitterOnLocationUpdate(callback);
+  },
+  /**
+   * Register a callback for tracking errors.
+   */
+  onError(callback) {
+    return emitterOnError(callback);
+  },
+  /**
+   * Get the current tracking status.
+   */
+  async getStatus() {
+    const jsonString = await native().getStatus();
+    return JSON.parse(jsonString);
+  },
+  /**
+   * Get the total number of locations currently queued for sync.
+   *
+   * @throws Error with code NOT_CONFIGURED if called before configure()
+   */
+  async getQueuedLocations() {
+    if (!isConfigured) {
+      const error = new Error('LiveTracking is not configured. Call configure() before getQueuedLocations().');
+      error.code = 'NOT_CONFIGURED';
+      throw error;
+    }
+    return native().getQueuedLocations();
+  },
+  /**
+   * Get the number of queued locations per target path.
+   *
+   * @throws Error with code NOT_CONFIGURED if called before configure()
+   */
+  async getQueuedLocationsByTarget() {
+    if (!isConfigured) {
+      const error = new Error('LiveTracking is not configured. Call configure() before getQueuedLocationsByTarget().');
+      error.code = 'NOT_CONFIGURED';
+      throw error;
+    }
+    const jsonString = await native().getQueuedLocationsByTarget();
+    return JSON.parse(jsonString);
+  }
+};
+export default LiveTracking;
+//# sourceMappingURL=LiveTracking.js.map

package/lib/module/LiveTracking.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NativeLiveTracking","onLocationUpdate","emitterOnLocationUpdate","onError","emitterOnError","validateConfig","applyDefaults","native","Error","isConfigured","_resetConfiguredStateForTesting","LiveTracking","configure","config","validationResult","valid","errorMessages","errors","map","e","field","message","join","finalConfig","jsonString","JSON","stringify","MAX_PAYLOAD_BYTES","length","start","stop","callback","getStatus","parse","getQueuedLocations","error","code","getQueuedLocationsByTarget"],"sourceRoot":"../../src","sources":["LiveTracking.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/NativeLiveTracking.js

@@ -0,0 +1,16 @@
+/**
+ * Codegen spec for react-native-live-tracking.
+ *
+ * Uses TurboModuleRegistry.get (not getEnforcing) so that a missing or
+ * not-yet-registered module returns null instead of throwing synchronously.
+ * A top-level throw would corrupt the module graph and leave upstream
+ * importers (TrackingProvider, AppNavigator) with undefined module records.
+ *
+ * File must be named Native*.ts and live in the codegenConfig.jsSrcsDir
+ * for RN's codegen to pick it up.
+ */
+
+import { TurboModuleRegistry, NativeModules } from 'react-native';
+// Try TurboModule first (new arch with codegen), fall back to Bridge (old arch / interop)
+export default TurboModuleRegistry.get('LiveTracking') ?? NativeModules.LiveTracking;
+//# sourceMappingURL=NativeLiveTracking.js.map

package/lib/module/NativeLiveTracking.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TurboModuleRegistry","NativeModules","get","LiveTracking"],"sourceRoot":"../../src","sources":["NativeLiveTracking.ts"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,mBAAmB,EAAEC,aAAa,QAAQ,cAAc;AAajE;AACA,eAAgBD,mBAAmB,CAACE,GAAG,CAAO,cAAc,CAAC,IAC3DD,aAAa,CAACE,YAAY","ignoreList":[]}

package/lib/module/filters/distanceTimeFilter.js

@@ -0,0 +1,58 @@
+/**
+ * Distance/Time Matrix filter for location updates.
+ *
+ * This filter implements the battery optimization strategy that accepts a new
+ * location update based on the selected mode:
+ * - 'both' (default): BOTH time and distance conditions must be met
+ * - 'interval': only the time condition must be met
+ * - 'distance': only the distance condition must be met
+ *
+ * @packageDocumentation
+ */
+
+import { calculateDistance } from '../utils/distance';
+
+/**
+ * Configuration subset required by the distance/time filter.
+ */
+
+/**
+ * Determines whether a new location should be accepted based on the
+ * Distance/Time Matrix filter criteria.
+ *
+ * The filtering strategy depends on `config.mode`:
+ * - 'both': accepted only if both time and distance conditions are met
+ * - 'interval': accepted only if enough time has elapsed
+ * - 'distance': accepted only if enough distance has been covered
+ *
+ * @param lastLocation - The most recently accepted location
+ * @param newLocation - The candidate location to evaluate
+ * @param config - Filter configuration with intervalMs, distanceFilterMeters, and mode
+ * @returns `true` if the new location should be accepted, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const accepted = shouldAcceptLocation(
+ *   { latitude: -6.2088, longitude: 106.8456, timestamp: 1700000000000, accuracy: 5, speed: null, altitude: null, bearing: null },
+ *   { latitude: -6.2090, longitude: 106.8460, timestamp: 1700000015000, accuracy: 5, speed: 1.2, altitude: null, bearing: null },
+ *   { intervalMs: 10000, distanceFilterMeters: 10, mode: 'both' }
+ * );
+ * ```
+ */
+export function shouldAcceptLocation(lastLocation, newLocation, config) {
+  const mode = config.mode ?? 'both';
+  const timeDiff = newLocation.timestamp - lastLocation.timestamp;
+  const distance = calculateDistance(lastLocation.latitude, lastLocation.longitude, newLocation.latitude, newLocation.longitude);
+  const timeMet = timeDiff >= config.intervalMs;
+  const distanceMet = distance >= config.distanceFilterMeters;
+  switch (mode) {
+    case 'interval':
+      return timeMet;
+    case 'distance':
+      return distanceMet;
+    case 'both':
+    default:
+      return timeMet && distanceMet;
+  }
+}
+//# sourceMappingURL=distanceTimeFilter.js.map

package/lib/module/filters/distanceTimeFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["calculateDistance","shouldAcceptLocation","lastLocation","newLocation","config","mode","timeDiff","timestamp","distance","latitude","longitude","timeMet","intervalMs","distanceMet","distanceFilterMeters"],"sourceRoot":"../../../src","sources":["filters/distanceTimeFilter.ts"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,iBAAiB,QAAQ,mBAAmB;;AAGrD;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAClCC,YAA0B,EAC1BC,WAAyB,EACzBC,MAAgC,EACvB;EACT,MAAMC,IAAI,GAAGD,MAAM,CAACC,IAAI,IAAI,MAAM;EAClC,MAAMC,QAAQ,GAAGH,WAAW,CAACI,SAAS,GAAGL,YAAY,CAACK,SAAS;EAC/D,MAAMC,QAAQ,GAAGR,iBAAiB,CAChCE,YAAY,CAACO,QAAQ,EACrBP,YAAY,CAACQ,SAAS,EACtBP,WAAW,CAACM,QAAQ,EACpBN,WAAW,CAACO,SACd,CAAC;EAED,MAAMC,OAAO,GAAGL,QAAQ,IAAIF,MAAM,CAACQ,UAAU;EAC7C,MAAMC,WAAW,GAAGL,QAAQ,IAAIJ,MAAM,CAACU,oBAAoB;EAE3D,QAAQT,IAAI;IACV,KAAK,UAAU;MACb,OAAOM,OAAO;IAChB,KAAK,UAAU;MACb,OAAOE,WAAW;IACpB,KAAK,MAAM;IACX;MACE,OAAOF,OAAO,IAAIE,WAAW;EACjC;AACF","ignoreList":[]}

package/lib/module/index.js

@@ -0,0 +1,32 @@
+/**
+ * react-native-live-tracking
+ *
+ * Real-time location tracking library for React Native with Firebase synchronization.
+ * Supports both TurboModules (new architecture) and Bridge (old architecture).
+ *
+ * @packageDocumentation
+ */
+
+import LiveTracking from './LiveTracking';
+export default LiveTracking;
+export { default as LiveTracking } from './LiveTracking';
+
+// Re-export all types
+export { TrackingState } from './types';
+// Event listener functions
+export { onLocationUpdate, onError, removeAllListeners } from './EventEmitter';
+
+// Configuration validation utilities
+export { validateConfig, applyDefaults } from './validation';
+
+// Distance calculation utility
+export { calculateDistance } from './utils/distance';
+
+// Distance/Time Matrix filter
+export { shouldAcceptLocation } from './filters/distanceTimeFilter';
+
+// Location serialization for Firebase
+export { serializeLocationForTarget } from './serialization/locationSerializer';
+// Retry/backoff utilities
+export { calculateBackoffDelay, shouldRetry } from './utils/retry';
+//# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["LiveTracking","default","TrackingState","onLocationUpdate","onError","removeAllListeners","validateConfig","applyDefaults","calculateDistance","shouldAcceptLocation","serializeLocationForTarget","calculateBackoffDelay","shouldRetry"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,OAAOA,YAAY,MAAM,gBAAgB;AAEzC,eAAeA,YAAY;AAC3B,SAASC,OAAO,IAAID,YAAY,QAAQ,gBAAgB;;AAExD;AACA,SAASE,aAAa,QAAQ,SAAS;AAkBvC;AACA,SAASC,gBAAgB,EAAEC,OAAO,EAAEC,kBAAkB,QAAQ,gBAAgB;;AAE9E;AACA,SAASC,cAAc,EAAEC,aAAa,QAAQ,cAAc;;AAE5D;AACA,SAASC,iBAAiB,QAAQ,kBAAkB;;AAEpD;AACA,SAASC,oBAAoB,QAAQ,8BAA8B;;AAEnE;AACA,SAASC,0BAA0B,QAAQ,oCAAoC;AAG/E;AACA,SAASC,qBAAqB,EAAEC,WAAW,QAAQ,eAAe","ignoreList":[]}

package/lib/module/serialization/locationSerializer.js

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+export 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/module/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;AACA,OAAO,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/module/types.js

@@ -0,0 +1,94 @@
+/**
+ * TypeScript type definitions for react-native-live-tracking.
+ *
+ * @packageDocumentation
+ */
+
+// ─── Enums ───────────────────────────────────────────────────────────────────
+
+/**
+ * Internal state machine for tracking lifecycle.
+ */
+export let 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/module/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["TrackingState"],"sourceRoot":"../../src","sources":["types.ts"],"mappings":"AAAA;AACA;AACA;AACA;AACA;;AAEA;;AAEA;AACA;AACA;AACA,WAAYA,aAAa,0BAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAbA,aAAa;EAAA,OAAbA,aAAa;AAAA;;AAQzB;;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/module/utils/distance.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+export const 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
+ * ```
+ */
+export 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/module/utils/distance.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["EARTH_RADIUS_METERS","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;AACA,OAAO,MAAMA,mBAAmB,GAAG,OAAO;;AAE1C;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,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;AACA,OAAO,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,OAAOZ,mBAAmB,GAAGe,CAAC;AAChC","ignoreList":[]}

package/lib/module/utils/retry.js

@@ -0,0 +1,72 @@
+/**
+ * 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 */
+export const DEFAULT_BASE_DELAY = 1000;
+
+/** Default maximum jitter in milliseconds (±) to avoid thundering herd */
+export const DEFAULT_MAX_JITTER = 200;
+
+/** Maximum retry attempts for sync targets using 'set' or 'update' write methods */
+export const MAX_RETRIES_SET_UPDATE = 3;
+
+/** Maximum retry attempts for sync targets using 'push' write method */
+export const 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);
+ * ```
+ */
+export 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
+ * ```
+ */
+export function shouldRetry(attempt, maxRetries) {
+  return attempt <= maxRetries;
+}
+//# sourceMappingURL=retry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["DEFAULT_BASE_DELAY","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;AACA,OAAO,MAAMA,kBAAkB,GAAG,IAAI;;AAEtC;AACA,OAAO,MAAMC,kBAAkB,GAAG,GAAG;;AAErC;AACA,OAAO,MAAMC,sBAAsB,GAAG,CAAC;;AAEvC;AACA,OAAO,MAAMC,gBAAgB,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;AACA,OAAO,SAASC,qBAAqBA,CACnCC,OAAe,EACfC,SAAiB,GAAGN,kBAAkB,EACtCO,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;AACA,OAAO,SAASG,WAAWA,CAACT,OAAe,EAAEU,UAAkB,EAAW;EACxE,OAAOV,OAAO,IAAIU,UAAU;AAC9B","ignoreList":[]}