geofirestore-core/dist/utils.d.ts

Lightweight location-based querying and encoding of Firebase Firestore Documents for geofirestore.

import { GeoFirestoreTypes } from './definitions';
export declare const BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz";
export declare const BITS_PER_CHAR = 5;
export declare const CUSTOM_KEY = "coordinates";
export declare const E2 = 0.00669447819799;
export declare const EARTH_EQ_RADIUS = 6378137;
export declare const EARTH_MERI_CIRCUMFERENCE = 40007860;
export declare const EPSILON = 1e-12;
export declare const MAXIMUM_BITS_PRECISION: number;
export declare const METERS_PER_DEGREE_LATITUDE = 110574;
/**
 * Calculates the maximum number of bits of a geohash to get a bounding box that is larger than a given size at the given coordinate.
 *
 * @param coordinate The coordinate as a Firestore GeoPoint.
 * @param size The size of the bounding box.
 * @return The number of bits necessary for the geohash.
 */
export declare function boundingBoxBits(coordinate: GeoFirestoreTypes.cloud.GeoPoint | GeoFirestoreTypes.web.GeoPoint, size: number): number;
/**
 * Calculates eight points on the bounding box and the center of a given circle. At least one geohash of these nine coordinates, truncated'
 * to a precision of at most radius, are guaranteed to be prefixes of any geohash that lies within the circle.
 *
 * @param center The center given as Firestore GeoPoint.
 * @param radius The radius of the circle.
 * @return The eight bounding box points.
 */
export declare function boundingBoxCoordinates(center: GeoFirestoreTypes.cloud.GeoPoint | GeoFirestoreTypes.web.GeoPoint, radius: number): GeoFirestoreTypes.cloud.GeoPoint[] | GeoFirestoreTypes.web.GeoPoint[];
/**
 * Function which validates GeoPoints then calculates the distance, in kilometers, between them.
 *
 * @param location1 The GeoPoint of the first location.
 * @param location2 The GeoPoint of the second location.
 * @return The distance, in kilometers, between the inputted locations.
 */
export declare function calculateDistance(location1: GeoFirestoreTypes.cloud.GeoPoint | GeoFirestoreTypes.web.GeoPoint, location2: GeoFirestoreTypes.cloud.GeoPoint | GeoFirestoreTypes.web.GeoPoint): number;
/**
 * Decodes the GeoDocument data. Returns non-decoded data if decoding fails.
 *
 * @param data The data encoded as a GeoDocument object.
 * @param center The center to calculate the distance of the Document from the query origin.
 * @return The decoded Firestore document or non-decoded data if decoding fails in an object including distance from origin.
 */
export declare function decodeGeoQueryDocumentSnapshotData(data: GeoFirestoreTypes.GeoDocumentData, center?: GeoFirestoreTypes.web.GeoPoint | GeoFirestoreTypes.cloud.GeoPoint): {
    data: () => GeoFirestoreTypes.GeoDocumentData;
    distance: number;
};
/**
 * Converts degrees to radians.
 *
 * @param degrees The number of degrees to be converted to radians.
 * @return The number of radians equal to the inputted number of degrees.
 */
export declare function degreesToRadians(degrees: number): number;
/**
 * Finds GeoPoint in a document.
 *
 * @param document A Firestore document.
 * @param customKey The key of the document to use as the location. Otherwise we default to `coordinates`.
 * @param flag Tells function supress errors.
 * @return The GeoPoint for the location field of a document.
 */
export declare function findGeoPoint(document: GeoFirestoreTypes.DocumentData, customKey?: string, flag?: boolean): GeoFirestoreTypes.web.GeoPoint | GeoFirestoreTypes.cloud.GeoPoint;
/**
 * Creates GeoFirestore QueryDocumentSnapshot by pulling data out of original Firestore QueryDocumentSnapshot and strip GeoFirsetore
 * Document data, such as geohash and coordinates.
 *
 * @param snapshot The QueryDocumentSnapshot.
 * @param center The center to calculate the distance of the Document from the query origin.
 * @return The snapshot as a GeoFirestore QueryDocumentSnapshot.
 */
export declare function generateGeoQueryDocumentSnapshot(snapshot: GeoFirestoreTypes.web.QueryDocumentSnapshot | GeoFirestoreTypes.cloud.QueryDocumentSnapshot, center?: GeoFirestoreTypes.web.GeoPoint | GeoFirestoreTypes.cloud.GeoPoint): GeoFirestoreTypes.QueryDocumentSnapshot;
/**
 * Creates an array of `Query` objects that query the appropriate geohashes based on the radius and center GeoPoint of the query criteria.
 * @param query The Firestore Query instance.
 * @param queryCriteria The query criteria of geo based queries, includes field such as center, radius, and limit.
 * @return Array of Queries to search against.
 */
export declare function generateQuery(query: GeoFirestoreTypes.cloud.Query | GeoFirestoreTypes.web.Query, queryCriteria: GeoFirestoreTypes.QueryCriteria): GeoFirestoreTypes.web.Query[];
/**
 * Calculates a set of queries to fully contain a given circle. A query is a GeoPoint where any geohash is guaranteed to be
 * lexiographically larger then start and smaller than end.
 *
 * @param center The center given as a GeoPoint.
 * @param radius The radius of the circle.
 * @return An array of geohashes containing a GeoPoint.
 */
export declare function geohashQueries(center: GeoFirestoreTypes.cloud.GeoPoint | GeoFirestoreTypes.web.GeoPoint, radius: number): string[][];
/**
 * Calculates the bounding box query for a geohash with x bits precision.
 *
 * @param geohash The geohash whose bounding box query to generate.
 * @param bits The number of bits of precision.
 * @return A [start, end] pair of geohashes.
 */
export declare function geohashQuery(geohash: string, bits: number): string[];
/**
 * Calculates the bits necessary to reach a given resolution, in meters, for the latitude.
 *
 * @param resolution The bits necessary to reach a given resolution, in meters.
 * @return Bits necessary to reach a given resolution, in meters, for the latitude.
 */
export declare function latitudeBitsForResolution(resolution: number): number;
/**
 * Calculates the base 2 logarithm of the given number.
 *
 * @param x A number
 * @return The base 2 logarithm of a number
 */
export declare function log2(x: number): number;
/**
 * Calculates the bits necessary to reach a given resolution, in meters, for the longitude at a given latitude.
 *
 * @param resolution The desired resolution.
 * @param latitude The latitude used in the conversion.
 * @return The bits necessary to reach a given resolution, in meters.
 */
export declare function longitudeBitsForResolution(resolution: number, latitude: number): number;
/**
 * Calculates the number of degrees a given distance is at a given latitude.
 *
 * @param distance The distance to convert.
 * @param latitude The latitude at which to calculate.
 * @return The number of degrees the distance corresponds to.
 */
export declare function metersToLongitudeDegrees(distance: number, latitude: number): number;
/**
 * Decodes a query string to a query
 *
 * @param str The encoded query.
 * @return The decoded query as a [start, end] pair.
 */
export declare function stringToQuery(str: string): string[];
/**
 * Encodes a query as a string for easier indexing and equality.
 *
 * @param query The query to encode.
 * @return The encoded query as string.
 */
export declare function queryToString(query: string[]): string;
/**
 * Returns a 'GeoPoint.' (Kind of fake, but get's the job done!)
 *
 * @param latitude Latitude for GeoPoint.
 * @param longitude Longitude for GeoPoint.
 * @return Firestore "GeoPoint"
 */
export declare function toGeoPoint(latitude: number, longitude: number): GeoFirestoreTypes.cloud.GeoPoint | GeoFirestoreTypes.web.GeoPoint;
/**
 * Wraps the longitude to [-180,180].
 *
 * @param longitude The longitude to wrap.
 * @return longitude The resulting longitude.
 */
export declare function wrapLongitude(longitude: number): number;