@mapvina-com/mapvina-react-native 1.0.0

package/src/modules/offline/OfflineManager.ts

@@ -0,0 +1,428 @@
+import { type EventSubscription } from "react-native";
+
+import NativeOfflineModule from "./NativeOfflineModule";
+import { OfflinePack, type OfflinePackStatus } from "./OfflinePack";
+import type { LngLatBounds } from "../../types/LngLatBounds";
+
+export interface OfflinePackCreateOptions {
+  mapStyle: string;
+  bounds: LngLatBounds;
+  minZoom?: number;
+  maxZoom?: number;
+
+  /**
+   * User-provided metadata object.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Represents the offline pack download state
+ */
+export type OfflinePackDownloadState = "inactive" | "active" | "complete";
+
+export type OfflinePackError = {
+  id: string;
+  message: string;
+};
+
+export type OfflinePackProgressListener = (
+  offlinePack: OfflinePack,
+  status: OfflinePackStatus,
+) => void;
+export type OfflinePackErrorListener = (
+  offlinePack: OfflinePack,
+  error: OfflinePackError,
+) => void;
+
+/**
+ * OfflineManager implements a singleton (shared object) that manages offline
+ * packs. All of this class's instance methods are asynchronous, reflecting the
+ * fact that offline resources are stored in a database. The shared object
+ * maintains a canonical collection of offline packs.
+ */
+class OfflineManager {
+  private initialized: boolean;
+
+  private readonly offlinePacks: Record<string, OfflinePack>;
+
+  private readonly progressListeners: Record<
+    string,
+    OfflinePackProgressListener
+  >;
+  private readonly errorListeners: Record<string, OfflinePackErrorListener>;
+
+  private subscriptionProgress: EventSubscription | null;
+  private subscriptionError: EventSubscription | null;
+
+  constructor() {
+    this.initialized = false;
+
+    this.offlinePacks = {};
+
+    this.progressListeners = {};
+    this.errorListeners = {};
+
+    this.handleProgress = this.handleProgress.bind(this);
+    this.onError = this.onError.bind(this);
+
+    this.subscriptionProgress = null;
+    this.subscriptionError = null;
+  }
+
+  /**
+   * Creates and registers an offline pack that downloads the resources needed to
+   * use the given region offline.
+   *
+   * @param options - Create options for offline pack that specifies zoom levels, style url, and
+   *   the region to download.
+   * @param progressListener - Callback that listens for status events while downloading the offline
+   *   resource.
+   * @param errorListener - Callback that listens for status events while downloading the offline
+   *   resource.
+   * @returns The created offline pack with its generated ID.
+   *
+   * @example
+   * ```ts
+   * const progressListener = (offlineRegion, status) =>
+   *   console.log(offlineRegion, status);
+   * const errorListener = (offlineRegion, error) =>
+   *   console.log(offlineRegion, error);
+   *
+   * const offlinePack = await OfflineManager.createPack(
+   *   {
+   *     mapStyle: "https://demotiles.mapvina.com/tiles/tiles.json",
+   *     minZoom: 14,
+   *     maxZoom: 20,
+   *     bounds: [west, south, east, north],
+   *     metadata: { customValue: "myValue" },
+   *   },
+   *   progressListener,
+   *   errorListener,
+   * );
+   * ```
+   */
+  async createPack(
+    options: OfflinePackCreateOptions,
+    progressListener: OfflinePackProgressListener,
+    errorListener: OfflinePackErrorListener,
+  ): Promise<OfflinePack> {
+    await this.initialize();
+
+    const offlinePackOptions = {
+      mapStyle: options.mapStyle,
+      bounds: options.bounds,
+      minZoom: options.minZoom ?? 10,
+      maxZoom: options.maxZoom ?? 20,
+      metadata: JSON.stringify(options.metadata ?? {}),
+    };
+
+    const nativeOfflinePack =
+      await NativeOfflineModule.createPack(offlinePackOptions);
+    const offlinePack = new OfflinePack(nativeOfflinePack);
+
+    this.offlinePacks[offlinePack.id] = offlinePack;
+    await this.addListener(offlinePack.id, progressListener, errorListener);
+
+    return offlinePack;
+  }
+
+  /**
+   * Invalidates the specified offline pack. This method checks that the tiles in
+   * the specified offline pack match those from the server. Local tiles that do
+   * not match the latest version on the server are updated.
+   *
+   * This is more efficient than deleting the offline pack and downloading it
+   * again. If the data stored locally matches that on the server, new data will
+   * not be downloaded.
+   *
+   * @param id - ID of the OfflinePack.
+   *
+   * @example
+   * ```ts
+   * await OfflineManager.invalidatePack(pack.id);
+   * ```
+   */
+  async invalidatePack(id: string): Promise<void> {
+    await this.initialize();
+
+    const offlinePack = await this.getPack(id);
+    await NativeOfflineModule.invalidatePack(offlinePack.id);
+  }
+
+  /**
+   * Unregisters the given OfflinePack and allows resources that are no longer
+   * required by any remaining packs to be potentially freed.
+   *
+   * @param id - ID of the OfflinePack.
+   *
+   * @example
+   * ```ts
+   * await OfflineManager.deletePack(pack.id);
+   * ```
+   */
+  async deletePack(id: string): Promise<void> {
+    await this.initialize();
+
+    const offlinePack = await this.getPack(id);
+    await NativeOfflineModule.deletePack(offlinePack.id);
+    delete this.offlinePacks[offlinePack.id];
+  }
+
+  /**
+   * Forces a revalidation of the tiles in the ambient cache and downloads a fresh
+   * version of the tiles from the tile server. This is the recommend method for
+   * clearing the cache. This is the most efficient method because tiles in the
+   * ambient cache are re-downloaded to remove outdated data from a device. It
+   * does not erase resources from the ambient cache or delete the database, which
+   * can be computationally expensive operations that may carry unintended side
+   * effects.
+   *
+   * @example
+   * ```ts
+   * await OfflineManager.invalidateAmbientCache();
+   * ```
+   */
+  async invalidateAmbientCache(): Promise<void> {
+    await this.initialize();
+    await NativeOfflineModule.invalidateAmbientCache();
+  }
+
+  /**
+   * Erases resources from the ambient cache. This method clears the cache and
+   * decreases the amount of space that map resources take up on the device.
+   *
+   * @example
+   * ```ts
+   * await OfflineManager.clearAmbientCache();
+   * ```
+   */
+  async clearAmbientCache(): Promise<void> {
+    await this.initialize();
+    await NativeOfflineModule.clearAmbientCache();
+  }
+
+  /**
+   * Sets the maximum size of the ambient cache in bytes. Disables the ambient
+   * cache if set to 0. This method may be computationally expensive because it
+   * will erase resources from the ambient cache if its size is decreased.
+   *
+   * @param size - Size of ambient cache.
+   *
+   * @example
+   * await OfflineManager.setMaximumAmbientCacheSize(5000000);
+   */
+  async setMaximumAmbientCacheSize(size: number): Promise<void> {
+    await this.initialize();
+    await NativeOfflineModule.setMaximumAmbientCacheSize(size);
+  }
+
+  /**
+   * Deletes the existing database, which includes both the ambient cache and
+   * offline packs, then reinitializes it.
+   *
+   * @example
+   * ```ts
+   * await OfflineManager.resetDatabase();
+   * ```
+   */
+  async resetDatabase(): Promise<void> {
+    await this.initialize();
+    await NativeOfflineModule.resetDatabase();
+  }
+
+  /**
+   * Retrieves all the current offline packs that are stored in the database.
+   *
+   * @example
+   * const offlinePacks = await OfflineManager.getPacks();
+   */
+  async getPacks(): Promise<OfflinePack[]> {
+    await this.initialize();
+
+    return Object.values(this.offlinePacks);
+  }
+
+  /**
+   * Retrieves an offline pack that is stored in the database by ID.
+   *
+   * @example
+   * ```ts
+   * const offlinePack = await OfflineManager.getPack(offlinePack.id);
+   * ```
+   */
+  async getPack(id: string): Promise<OfflinePack> {
+    await this.initialize();
+    const offlinePack = this.offlinePacks[id];
+
+    if (!offlinePack) {
+      throw new Error(`OfflinePack ${id} not found`);
+    }
+
+    return offlinePack;
+  }
+
+  /**
+   * Sideloads offline db
+   *
+   * @param path - Path to offline tile db on file system.
+   *
+   * @example
+   * ```ts
+   * await OfflineManager.mergeOfflineRegions(path);
+   * ```
+   */
+  async mergeOfflineRegions(path: string): Promise<void> {
+    await this.initialize();
+    return NativeOfflineModule.mergeOfflineRegions(path);
+  }
+
+  /**
+   * Sets the maximum number of tiles that may be downloaded and stored on the
+   * current device. Consult the Terms of Service for your map tile host before
+   * changing this value.
+   *
+   * @param limit - Map tile limit count.
+   *
+   * @example
+   * ```ts
+   * OfflineManager.setTileCountLimit(1000);
+   * ```
+   */
+  setTileCountLimit(limit: number): void {
+    NativeOfflineModule.setTileCountLimit(limit);
+  }
+
+  /**
+   * Sets the period at which download status events will be sent over the React
+   * Native bridge. The default is 500ms.
+   *
+   * @param throttleValue - Event throttle value in ms.
+   *
+   * @example
+   * ```ts
+   * OfflineManager.setProgressEventThrottle(500);
+   * ```
+   */
+  setProgressEventThrottle(throttleValue: number): void {
+    NativeOfflineModule.setProgressEventThrottle(throttleValue);
+  }
+
+  /**
+   * Subscribe to download status/error events for the requested offline pack.
+   * Note that createPack calls this internally if listeners are provided.
+   *
+   * @param id - ID of the offline pack.
+   * @param progressListener - Callback that listens for status events while downloading the offline
+   *   resource.
+   * @param errorListener - Callback that listens for status events while downloading the offline
+   *   resource.
+   *
+   * @example
+   * ```ts
+   * const progressListener = (offlinePack, status) =>
+   *   console.log(offlinePack, status);
+   * const errorListener = (offlinePack, error) => console.log(offlinePack, error);
+   * OfflineManager.addListener(pack.id, progressListener, errorListener);
+   * ```
+   */
+  async addListener(
+    id: string,
+    progressListener: OfflinePackProgressListener,
+    errorListener: OfflinePackErrorListener,
+  ): Promise<void> {
+    const totalProgressListeners = Object.keys(this.progressListeners).length;
+    if (totalProgressListeners === 0) {
+      this.subscriptionProgress = NativeOfflineModule.onProgress(
+        this.handleProgress,
+      );
+    }
+    this.progressListeners[id] = progressListener;
+
+    const totalErrorListeners = Object.keys(this.errorListeners).length;
+    if (totalErrorListeners === 0) {
+      this.subscriptionError = NativeOfflineModule.onError(this.onError);
+    }
+    this.errorListeners[id] = errorListener;
+
+    if (this.offlinePacks[id]) {
+      await NativeOfflineModule.setPackObserver(id);
+    }
+  }
+
+  /**
+   * Unsubscribes any listeners associated with the offline pack. Should be called
+   * when the component unmounts.
+   *
+   * @param packId - ID of the offline pack.
+   *
+   * @example
+   * ```ts
+   * useEffect(() => {
+   *   return () => {
+   *     OfflineManager.removeListener(pack.id);
+   *   };
+   * }, []);
+   * ```
+   */
+  removeListener(packId: string): void {
+    delete this.progressListeners[packId];
+    delete this.errorListeners[packId];
+
+    if (
+      Object.keys(this.progressListeners).length === 0 &&
+      this.subscriptionProgress
+    ) {
+      this.subscriptionProgress.remove();
+    }
+
+    if (
+      Object.keys(this.errorListeners).length === 0 &&
+      this.subscriptionError
+    ) {
+      this.subscriptionError.remove();
+    }
+  }
+
+  private async initialize(): Promise<boolean> {
+    if (this.initialized) {
+      return true;
+    }
+
+    const nativeOfflinePacks = await NativeOfflineModule.getPacks();
+
+    for (const nativeOfflinePack of nativeOfflinePacks) {
+      const offlinePack = new OfflinePack(nativeOfflinePack);
+
+      this.offlinePacks[offlinePack.id] = offlinePack;
+    }
+
+    this.initialized = true;
+    return true;
+  }
+
+  private handleProgress(event: OfflinePackStatus) {
+    const { id, state } = event;
+    const offlinePack = this.offlinePacks[id];
+
+    if (offlinePack) {
+      this.progressListeners[offlinePack.id]?.(offlinePack, event);
+    }
+
+    if (state === "complete") {
+      this.removeListener(id);
+    }
+  }
+
+  private onError(event: OfflinePackError) {
+    const { id } = event;
+
+    const offlinePack = this.offlinePacks[id];
+    if (offlinePack) {
+      this.errorListeners[offlinePack.id]?.(offlinePack, event);
+    }
+  }
+}
+
+const offlineManager = new OfflineManager();
+export { offlineManager as OfflineManager };

package/src/modules/offline/OfflinePack.ts

@@ -0,0 +1,44 @@
+import NativeOfflineModule, {
+  type NativeOfflinePack,
+} from "./NativeOfflineModule";
+import type { OfflinePackDownloadState } from "./OfflineManager";
+import type { LngLatBounds } from "../../types/LngLatBounds";
+
+export type OfflinePackStatus = {
+  id: string;
+  state: OfflinePackDownloadState;
+  percentage: number;
+  completedResourceCount: number;
+  completedResourceSize: number;
+  completedTileCount: number;
+  completedTileSize: number;
+  requiredResourceCount: number;
+};
+
+export class OfflinePack {
+  /** Unique Identifier (UUID), auto-generated natively during creation. */
+  public id: string;
+
+  /** User-provided metadata object. */
+  public metadata: Record<string, unknown>;
+
+  public bounds: LngLatBounds;
+
+  constructor(pack: NativeOfflinePack) {
+    this.id = pack.id;
+    this.bounds = pack.bounds as LngLatBounds;
+    this.metadata = JSON.parse(pack.metadata);
+  }
+
+  async status(): Promise<OfflinePackStatus> {
+    return NativeOfflineModule.getPackStatus(this.id);
+  }
+
+  async resume(): Promise<void> {
+    return NativeOfflineModule.resumePackDownload(this.id);
+  }
+
+  async pause(): Promise<void> {
+    return NativeOfflineModule.pausePackDownload(this.id);
+  }
+}

package/src/modules/static-map/NativeStaticMapModule.ts

@@ -0,0 +1,26 @@
+import type { CodegenTypes, TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+interface NativeStaticMapCreateOptions {
+  center?: CodegenTypes.Double[];
+  zoom?: CodegenTypes.Double;
+  bearing?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  pitch?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+
+  bounds?: CodegenTypes.Double[];
+
+  mapStyle: string;
+
+  width: CodegenTypes.Int32;
+  height: CodegenTypes.Int32;
+
+  output: "base64" | "file";
+
+  logo?: boolean;
+}
+
+export interface Spec extends TurboModule {
+  createImage(options: NativeStaticMapCreateOptions): Promise<string>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("MLRNStaticMapModule");

package/src/modules/static-map/StaticMapManager.ts

@@ -0,0 +1,127 @@
+import type { LngLat } from "../../types/LngLat";
+import type { LngLatBounds } from "../../types/LngLatBounds";
+import NativeStaticMapModule from "./NativeStaticMapModule";
+
+export interface StaticMapOptions {
+  /**
+   * Mapvina style - either a URL or a Style JSON.
+   *
+   * @see {@link https://mapvina.io/github/mapvina-style-spec/}
+   */
+  mapStyle: string | object;
+
+  /**
+   * Width of the image in pixels.
+   */
+  width: number;
+
+  /**
+   * Height of the image in pixels.
+   */
+  height: number;
+
+  /**
+   * Defines the way the image is returned.
+   *
+   * - "base64": base64 encoded string of the image
+   * - "file": URI to a temporary file image
+   */
+  output: "base64" | "file";
+
+  /**
+   * Toggle the MapVina logo on the image.
+   *
+   * MapVina doesn't require you to display the logo.
+   */
+  logo?: boolean;
+}
+
+export type StaticMapCenterOptions = StaticMapOptions & {
+  /**
+   * The center coordinate of the map.
+   */
+  center: LngLat;
+
+  /**
+   * The zoom level of the map.
+   */
+  zoom?: number;
+
+  /**
+   * The bearing (rotation) of the map.
+   */
+  bearing?: number;
+
+  /**
+   * The pitch of the map.
+   */
+  pitch?: number;
+};
+
+export type StaticMapBoundsOptions = StaticMapOptions & {
+  /**
+   * The corners of a box around which the map should bound.
+   */
+  bounds: LngLatBounds;
+};
+
+export type StaticMapCreateOptions =
+  | (StaticMapCenterOptions & { bounds?: never })
+  | (StaticMapBoundsOptions & {
+    center?: never;
+    zoom?: never;
+    bearing?: never;
+    pitch?: never;
+  });
+
+/**
+ * The StaticMapManager creates static images of a map.
+ */
+class StaticMapManager {
+  /**
+   * Creates a static image of a map. Images are always in PNG format.
+   *
+   * @param options -
+   *
+   * @example Create static map with center, returning the URI to the temporary PNG file
+   * ```ts
+   * const uri = await StaticMapManager.createImage({
+   *   center: [-74.12641, 40.797968],
+   *   zoom: 12,
+   *   bearing: 20,
+   *   pitch: 30,
+   *   mapStyle: "https://maps.mapvina.com/styles/v2/streets.json?key=public_key",
+   *   width: 128,
+   *   height: 64,
+   *   output: "file",
+   * });
+   * ```
+   *
+   * @example Create a static map with bounds, returning a base64 encoded PNG
+   * ```ts
+   * const uri = await StaticMapManager.createImage({
+   *   bounds: [
+   *     [-74.12641, 40.797968],
+   *     [-74.143727, 40.772177],
+   *   ],
+   *   mapStyle: "https://maps.mapvina.com/styles/v2/streets.json?key=public_key",
+   *   width: 128,
+   *   height: 64,
+   *   output: "base64",
+   * });
+   * ```
+   */
+  async createImage({
+    mapStyle,
+    ...options
+  }: StaticMapCreateOptions): Promise<string> {
+    return NativeStaticMapModule.createImage({
+      mapStyle:
+        typeof mapStyle === "string" ? mapStyle : JSON.stringify(mapStyle),
+      ...options,
+    });
+  }
+}
+
+const staticMapImageManager = new StaticMapManager();
+export { staticMapImageManager as StaticMapImageManager };

package/src/modules/transform-request/NativeTransformRequestModule.ts

@@ -0,0 +1,41 @@
+import type { TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+  addUrlTransform(
+    id: string,
+    match: string | null,
+    find: string,
+    replace: string,
+  ): void;
+
+  removeUrlTransform(id: string): void;
+
+  clearUrlTransforms(): void;
+
+  addUrlSearchParam(
+    id: string,
+    match: string | null,
+    name: string,
+    value: string,
+  ): void;
+
+  removeUrlSearchParam(id: string): void;
+
+  clearUrlSearchParams(): void;
+
+  addHeader(
+    id: string,
+    match: string | null,
+    name: string,
+    value: string,
+  ): void;
+
+  removeHeader(id: string): void;
+
+  clearHeaders(): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>(
+  "MLRNTransformRequestModule",
+);