@trakit/objects 0.0.1

package/API/Functions.d.ts

@@ -0,0 +1,191 @@
+import { ISerializable } from "./Interfaces/ISerializable";
+import { datetime } from "./Types";
+/**
+ * Checks for both null and undefined
+ * @param value The variable to check
+ */
+export declare function IS_NOTHING(value: any): value is null | undefined;
+/**
+ * Checks to see if the given parameter is a number object or number literal.
+ * @param value The variable to check
+ */
+export declare function IS_BOOLEAN(value: any): value is boolean;
+/**
+ * Checks to see if the given parameter is a number object or number literal.
+ * @param value The variable to check
+ */
+export declare function IS_NUMBER(value: any): value is number;
+/**
+ * Checks to see if the given parameter is a number object or number literal.
+ * @param value The variable to check
+ */
+export declare function IS_STRING(value: any): value is string;
+/**
+ * Checks to see if the given parameter is a function from this window or another.
+ * @param value The variable to check
+ */
+export declare function IS_FUNCTION(value: any): value is Function;
+/**
+ * Returns the name of the given value's type.
+ * @param value The variable to check
+ */
+export declare function OBJECT_TYPE(value: any): string;
+/**
+ * Almost the opposite of {@link isNaN}.
+ * Checks to see if the given parameter is a number object, or number literal, and that it is not {@code value|NaN|Infinity}.
+ * This method will return  {@code value|false} for values: {@code value|""}, {@code value|"1234"}, {@code value|null}, {@code value|undefined}, {@code value|true}, and {@code value|false}.
+ * @param value The variable to check
+ */
+export declare function IS_AN(value: any): value is number;
+/**
+ * Rounds a number to the desired number of decimal places. Using a negative places value will round to the nearest ten.
+ * @param number The number to be rounded
+ * @param places The number of decimal places.  Default is 0.
+ */
+export declare function ROUND_TO(number: number, places?: number): number;
+/**
+ * Clips a number to the specified minimum and maximum values.
+ * @param n	The number to clip
+ * @param min	Minimum allowable value
+ * @param max	Maximum allowable value
+ */
+export declare function CLIP(n: number, min: number, max: number): number;
+/**
+ * Calculates the Pythagorean length of a triangle given the length of the other two sides.
+ * @param width
+ * @param height
+ */
+export declare function PYTHAGORA(width: number, height: number): number;
+/**
+ * Parses a base-10 integer number from the given value.
+ * @param value
+ */
+export declare function ID(value: any): number;
+/**
+ * Creates a Date object out of the given value.
+ * @param value
+ */
+export declare function DATE(value?: Date | number | datetime): Date;
+/**
+ * An implementation of the Douglas-Peucker path reduction algorithm.
+ * @template TCoord			A type of coordinate like a pixel or lat/lng.
+ * @param source			Array of coordinates.
+ * @param triangleHeight	Callback which performs a triangle height calculation between first point, middle point, and last point.
+ * @param tolerance			The "kink" threshold.
+ * @returns					Elements in the array are true if they should be kept.
+ */
+export declare function DOUGLASPEUCKER_INTERNAL<TCoord>(source: TCoord[], triangleHeight: (first: TCoord, middle: TCoord, last: TCoord) => number, tolerance: number): boolean[];
+/**
+ * An implementation of the {@link https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm|Ramer-Douglas-Peucker} path reduction algorithm.
+ * The source array should be more than two items in length, otherwise reduction is pointless.
+ * The callback function returns a number (greater than zero) as the triangle height as defiend by three points; first point, middle point, and last point.
+ * The "kink" threshold is set using the tolerance argument which must be a number greater than or equal to zero.
+ * @template TCoord
+ * @param source						Array of coordinates of type "T".
+ * @param triangleHeight	Callback which performs a triangle height calculation between first point, middle point, and last point.
+ * @param tolerance						The "kink" threshold
+ */
+export declare function DOUGLASPEUCKER<TCoord>(source: TCoord[], triangleHeight: (first: TCoord, middle: TCoord, last: TCoord) => number, tolerance: number): TCoord[];
+/**
+ * Encodes the given string as a Provider password.
+ */
+export declare function PASSWORD_ENCODE(value: string): string;
+/**
+ * Decodes the given Provider password as a human readable value.
+ */
+export declare function PASSWORD_DECODE(value: string): string;
+/**
+ * Parses the input and returns a valid phone number prefixed by 1, or NaN if invalid.
+ * @param phone
+ * */
+export declare function PHONE_PARSE(phone: string | number | undefined): number;
+/**
+ * Internal method for returning a string representation of the given number, padded with zeros.
+ * @param num
+ * @param length
+ * @param decimals
+ * @param radix
+ */
+export declare function ZERO_PADDED(num: number, length: number, decimals?: number, radix?: number): string;
+/**
+ *
+ * @param source
+ * @param deep
+ * @returns
+ */
+export declare function MAP_TO_OBJECT(source: Map<any, any>, deep?: boolean): object;
+/**
+ *
+ * @param source
+ * @param deep
+ * @returns
+ */
+export declare function MAP_TO_OBJECT_PREDICATE<K, V>(source: Map<K, V>, predicate: (key: K, value: V) => [string, any]): object;
+/**
+ *
+ * @param source
+ * @param deep
+ * @returns
+ */
+export declare function MAP_TO_OBJECT_VALUE_JSON<V extends ISerializable>(source: Map<any, V>): object;
+/**
+ *
+ * @param map
+ * @param deep
+ * @returns
+ */
+export declare function OBJECT_TO_MAP_BY_PREDICATE<K, V>(source: object, predicate: (key: string, value: any) => [K, V]): Map<K, V>;
+/**
+ *
+ * @param map
+ * @param deep
+ * @returns
+ */
+export declare function OBJECT_TO_MAP(source: object, deep?: boolean): Map<string, any>;
+/**
+ *
+ * @param map
+ * @param deep
+ * @returns
+ */
+export declare function OBJECT_TO_MAP_KEY_CODIFIED(source: object, deep?: boolean): Map<string, any>;
+/**
+ *
+ * @param map
+ * @param deep
+ * @returns
+ */
+export declare function OBJECT_TO_MAP_KEY_ULONG(source: object, deep?: boolean): Map<number, any>;
+/**
+ *
+ * @param this
+ * @param value
+ * @returns
+ */
+export declare function STRING_TO_ENUM<T extends {
+    [key: string]: T;
+}>(this: T, value: string): T;
+/**
+ * Serializes a {@link Date} to an ISO string, or null (for use in {@link ISerializable.toJSON}).
+ * @param date
+ */
+export declare function JSON_DATE(date: Date): string | null;
+/**
+ * Serializes a {@link Number} as itself, or null instead of {@link NaN} (for use in {@link ISerializable.toJSON}).
+ * @param date
+ */
+export declare function JSON_NUMBER(num: number): number | null;
+/**
+ *
+ */
+export declare const WEEKDAYS: boolean[];
+/**
+ * Creates an array of 7 boolean values.
+ * Extra values from the input are ignored.
+ * @param days
+ */
+export declare function WEEKDAYS_PARSE(days: string | boolean[]): boolean[];
+/**
+ * Creates as string of 7 characters (either `1` or `0`).
+ */
+export declare function WEEKDAYS_JSON(days: string | boolean[]): string;

package/API/Geography/Functions.d.ts

@@ -0,0 +1,232 @@
+import { IPoint } from '../Geometry/Interfaces';
+import { int } from '../Types';
+import { ILatLng, ILatLngBounds } from './Interfaces';
+/**
+ * The radius of the Earth in meters taken from the GRS-80, NAD83, and WGS-84 standards.
+ */
+export declare const EARTH_RADIUS: number;
+/**
+ * The ellipsoid of the Earth taken from the WGS-84 standard.
+ * @default ~298.2572
+ */
+export declare const EARTH_ELLIPSOID: number;
+/**
+ * Inversion of the ellipsoid value for calculations.
+ */
+export declare const EARTH_FLATENING: number;
+/**
+ * The minor axis radius of an ellipsoid Earth as per WGS-84.
+ * @default ~6356752.3142
+ */
+export declare const EARTH_RADIUS_MINOR: number;
+/**
+ * The surface area of the Earth in meters squared.
+ * @default 511207893395811
+ */
+export declare const EARTH_SURFACE: number;
+/**
+ *
+ */
+export declare const EARTH_RADIUS_RATIO: number;
+/**
+ *
+ */
+export declare const EARTH_RADIUS_ECCENT: number;
+/**
+ *
+ */
+export declare const EARTH_RADIUS_COM: number;
+/**
+ *
+ */
+export declare const TILE_SIZE_PX: number;
+/**
+ *
+ */
+export declare const MAX_TILE_LAT: number;
+/**
+ *
+ */
+export declare const MAX_TILE_LNG: number;
+/**
+ * Determines the map width and height (in pixels) at a specified level of detail.
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ * @returns The map width and height in pixels.
+ */
+export declare function tileMapSize(zoom: int): int;
+/**
+ * Converts tile coordinates into pixel coordinates of the upper-left pixel of the specified tile.
+ * @param tile
+*/
+export declare function tileToPixel(tile: IPoint): IPoint;
+/**
+ * Converts pixel coordinates into tile coordinates of the tile containing the specified pixel.
+ * @param pixel
+ */
+export declare function pixelToTile(pixel: IPoint): IPoint;
+/**
+ * Converts a pixel coordinate into a LatLng at a specified level of detail.
+ * @param pixel
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ */
+export declare function pixelToLatlng(pixel: IPoint, zoom: int): ILatLng;
+/**
+ * Converts a LatLng into a pixel coordinate at a specified level of detail.
+ * @param latlng
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ */
+export declare function latlngToPixel(latlng: ILatLng, zoom: int): IPoint;
+/**
+ * Converts tile coordinates into a lat/lng boundary representing a complete tile.
+ * @param tile
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ * @param grow	Number of pixels to grow the tilesize (helps with detecting stroke/border overlaps).
+ */
+export declare function tileToBounds(tile: IPoint, zoom: int, grow?: number): ILatLngBounds;
+/**
+ * Converts pixel coordinates of a tile into a lat/lng boundary.
+ * @param pixel
+ * @param zoom	Level of detail, from 1 (lowest detail) to 23 (highest detail).
+ * @param grow	Number of pixels to grow the tilesize (helps with detecting stroke/border overlaps).
+ */
+export declare function pixelToBounds(pixel: IPoint, zoom: int, grow?: number): ILatLngBounds;
+/**
+ * Returns the number of meters per pixel at the given latitude and zoom level.
+ * @param lat
+ * @param zoom
+ */
+export declare function metresPerPixel(lat: number, zoom: int): number;
+/**
+ * Checks to see if a given latitude is at one of the poles.
+ * @param latitude
+ */
+export declare function LATITUDE_IS_POLE(latitude: number): boolean;
+/**
+ * Normalizes a latitude value between +/- 90.
+ * Values of greater than 90 are returned as 90, and values less than -90 are returned as -90.
+ * @param latitude
+ * @param edge
+ */
+export declare function LATITUDE_NORMALIZED(latitude: number, edge?: number): number;
+/**
+ * Normalizes a longitude value between +/- 180.
+ * Values of greater than 180 are returned as a negative difference of 360, and values less than -180 are returned as a positive difference of 360.
+ * @param longitude
+ * @param latitude	When given, will check if the latitude is a pole, and converts the longitude to zero.
+ */
+export declare function LONGITUDE_NORMALIZED(longitude: number, latitude?: number): number;
+/**
+ * The distance in meters before considering to coordinates to have the same location.
+ * @default 0.000000001
+ */
+export declare const MAX_SAME_DISTANCE = 1e-9;
+/**
+ * Bearing from coordinate A to coordinate B in degrees from North.
+ * @param first	The starting coordinate.
+ * @param last	The ending coordinate.
+ * @return		Degrees from North.
+ */
+export declare function LATLNG_ANGLE(first: ILatLng, last: ILatLng): number;
+/**
+ * Calculates the distance between two coordinates on a sphere.
+ * @param first	The starting coordinate.
+ * @param last	The ending coordinate.
+ */
+export declare function LATLNG_DISTANCE(first: ILatLng, last: ILatLng): number;
+/**
+ * Calculates the distance between two coordinates on a Bessel 1841 ellipsoid.
+ * @param start	The starting coordinate.
+ * @param end	The ending coordinate.
+ */
+export declare function LATLNG_DISTANCE_VINCENTY(start: ILatLng, end: ILatLng): number;
+/**
+ * Calculates the orthogonal height of a triangle.  The orthogonal height is
+ * calculated by drawing a line between the coordinate A and coordinate B,
+ * then getting the length of a line drawn up from the line to the mid
+ * coordinate at a 90 degree angle.
+ * @param first		Left-most coordinate on the great circle.
+ * @param middle	Top-most coordinate's latitude.
+ * @param last		Right-most coordinate's longitude on the great circle.
+ * @return			Value is negative when distance is to the right, and positive when distance to the left.
+ */
+export declare function LATLNG_GREAT_CIRCLE(first: ILatLng, middle: ILatLng, last: ILatLng): number;
+/**
+ * Calculates the final coordinate based on the given starting coordinate and vector.
+ * @param pin		The staring coordinate.
+ * @param meters	The distance away from this LatLng.
+ * @param bearing	The direction in which to calculate the new position in degrees from North.
+ * @throws {Error}	Either latitude or longitude is NaN.
+ */
+export declare function LATLNG_TRANSLATE(pin: ILatLng, meters: number, bearing: number): ILatLng;
+/**
+ * Calculates the mid-point between to given coordinate.
+ * @param first		Left-most coordinate.
+ * @param last		Right-most coordinate.
+ * @throws {Error}	Either latitude or longitude is NaN.
+ */
+export declare function LATLNG_MIDPOINT(first: ILatLng, last: ILatLng): ILatLng;
+/**
+ * Calculates the spherical-cap area occupied by the given radial distance.
+ * @param pin		The coordinate at which to calculate the area.
+ * @param radius	The distance from the centre of the circle to any point along the edge.
+ */
+export declare function SPHERECAP_AREA(pin: ILatLng, radius: number): void;
+/**
+ * Calculates the length of the given route.
+ * @param route
+ */
+export declare function ROUTE_LENGTH(route: ILatLng[]): number;
+/**
+ * Performs a Douglas-Peucker path reduction based on the given tolerance.
+ * @param route		The array of coordinates representing a path.
+ * @param tolerance	Distance (in meters) threshold for candidate coordinates.  Default is 0.
+ */
+export declare function ROUTE_PEUCKER(route: ILatLng[], tolerance: number): ILatLng[];
+/**
+ * An implementation of Google's Encoded Polyline Algorithm format.
+ * https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+ * @param route		The array of coordinates representing a path.
+ * @param precision			Optional number of decimal places to use to calculate the results.  Default is 5.
+ */
+export declare function ROUTE_ENCODE(route: ILatLng[], precision?: number): string;
+/**
+ * An implementation of Google's Decoded Polyline Algorithm format.
+ * https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+ * @param route			The encoded string which represents the coordinates in a path.
+ * @param precision			Optional number of decimal places used to recalculate the results.  Default is 5.
+ */
+export declare function ROUTE_DECODE(route: string, precision?: number): ILatLng[];
+/**
+ * Finds the widest section of the given route.
+ * This is useful for path reduction and reorientation.
+ * @param route		The array of coordinates representing a path
+ * @return			An array of three items; the first is the widest distance, and the others are the start and end index within the given route.
+ */
+export declare function GEOFENCE_WIDEST(route: ILatLng[]): [number, number, number];
+/**
+ * Performs a Douglas-Peucker path reduction on a polygon for the given
+ * tolerance. The start/end coordinates are variable and the end coordinate
+ * is trimmed from the result.
+ * @param route		The array of coordinates representing a path
+ * @param tolerance	Distance (in meters) threshold for candidate coordinates.  Default is 0.
+ */
+export declare function GEOFENCE_PEUCKER(route: ILatLng[], tolerance?: number): ILatLng[];
+/**
+ * Calculates the total area occupied by the given geofence.
+ * @param route		The array of coordinates representing a geofence.
+ * @throws {Error}	Not enough coordinates.
+ */
+export declare function GEOFENCE_AREA(route: ILatLng[]): number;
+/**
+ * A utility export function to determine if a given coordinate is inside the given geofence.
+ * @param route	The array of coordinates represents the path of the polygon.
+ * @param pin	The coordinate to be checked.
+ */
+export declare function GEOFENCE_CONTAINS(route: ILatLng[], pin: ILatLng): boolean;
+/**
+ * Wraps the given coordinates into a polygonal path.
+ * The given coordinates do not need to be a path.
+ * The returned path is not closed.
+ * @param coordinates	The array of coordinates on which to create the non-closed path
+ */
+export declare function GEOFENCE_WRAPPER(route: ILatLng[]): ILatLng[];

package/API/Geography/Interfaces.d.ts

@@ -0,0 +1,145 @@
+/**
+ * A coordinate on the Earth.
+ */
+export interface ILatLng {
+    /**
+     * Latitude.
+     */
+    lat: number;
+    /**
+     * Longitude.
+     */
+    lng: number;
+}
+/**
+ * Returns true if the given pin conforms to the {@link ILatLng} interface.
+ * @param pin
+ * @returns
+ */
+export declare function ILatLng_instanceOf(pin: any): pin is ILatLng;
+/**
+ *
+ * @param dot
+ * @returns
+ */
+export declare function ILatLng_clone(dot: ILatLng): ILatLng;
+/**
+ * GPS position information.
+ */
+export interface IPosition extends ILatLng {
+    /**
+    Speed
+     */
+    speed: number | null;
+    /**
+    Direction of travel
+     */
+    bearing: number | null;
+    /**
+    Distance in meters from the sea level
+     */
+    altitude: number | null;
+    /**
+    Threshold in meters for the accuracy of a position
+     */
+    accuracy: number | null;
+    /**
+    The Date/Time of the GPS reading
+     */
+    dts: string | Date;
+    /**
+    A better description of the current road-segment
+     */
+    streetAddress: IStreetAddress | null;
+    /**
+    The posted speed limit for the road segment
+     */
+    speedLimit: number | null;
+}
+/**
+ * Returns true if the given pin conforms to the {@link IPosition} interface.
+ * @param pin
+ * @returns
+ */
+export declare function IPosition_instanceOf(pin: any): pin is IPosition;
+/**
+ * A road segment description.
+ */
+export interface IStreetAddress {
+    /**
+     * House number.
+     */
+    number: string | null;
+    /**
+     * Full street name.
+     */
+    street: string | null;
+    /**
+     * City name.
+     */
+    city: string | null;
+    /**
+     * Region name.
+     */
+    region: string | null;
+    /**
+     * Province or state code.
+     * Codes should be a value from ISO 3166-2.
+     */
+    province: string;
+    /**
+     * Country code.
+     * Codes should be a value from ISO 3166-1 alpha-2.
+     */
+    country: string;
+    /**
+     * Postal or zip code.
+     */
+    postal: string | null;
+    /**
+     * Indicates that there is a toll for the current road segment.
+     */
+    isToll: boolean | null;
+}
+/**
+ * Returns true if the given pin conforms to the {@link IStreetAddress} interface.
+ * @param address
+ * @returns
+ */
+export declare function IStreetAddress_instanceOf(address: any): address is IStreetAddress;
+/**
+ * A rectangular boundary on a flat surface.
+ */
+export interface ILatLngBounds {
+    /**
+     * Northern latitude
+     */
+    north: number;
+    /**
+     * Eastern longitude
+     */
+    east: number;
+    /**
+     * Southern latitude
+     */
+    south: number;
+    /**
+     * Western longitude
+     */
+    west: number;
+}
+/**
+ * Returns true if the given box conforms to the {@link ILatLngBounds} interface.
+ * @param box
+ */
+export declare function ILatLngBounds_instanceOf(box: any): box is ILatLngBounds;
+/**
+ *
+ * @param box
+ * @returns
+ */
+export declare function ILatLngBounds_clone(box: ILatLngBounds): ILatLngBounds;
+/**
+ * The types used to extend a {@link LatLngBounds}'s edges.
+ */
+export type LatLngBoundsExpansion = ILatLng | ILatLngBounds | LatLngBoundsExpansion[];

package/API/Geography/LatLng.d.ts

@@ -0,0 +1,78 @@
+import { Point } from '../Geometry/Point';
+import { ILatLng } from './Interfaces';
+import { LatLngBounds } from './LatLngBounds';
+/**
+ * A coordinate on the Earth.
+ */
+export declare class LatLng implements ILatLng {
+    /**
+     * Let's consider the zero-zero coordinates to be invalid.
+     */
+    static readonly INVALID: LatLng;
+    /**
+     *
+     * @param json
+     */
+    static fromJSON(json: any): LatLng;
+    /**
+     * Latitude
+     */
+    readonly lat: number;
+    /**
+     * Longitude
+     */
+    readonly lng: number;
+    constructor(lat: number, lng: number);
+    /**
+     * Returns a string representation of this {@link LatLng}.
+     * @param delimiter	The boundary is delimited by a comma (,) by default, but you can override with your own value.
+     * @returns A string in the format of "lat,lng".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link LatLng}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): ILatLng;
+    /**
+     * Compares this LatLng to another to see if they are equivalent.
+     * @param other		The other LatLng to compare
+     * @param tolerance	Distance tolerance before considering two nearly identical coordinates to be equal.
+     */
+    isEqual(other: ILatLng, tolerance?: number): boolean;
+    /**
+     * Returns true if this coordinate is not NaN and not zero-zero.
+     */
+    isValid(): boolean;
+    /**
+     * Calculates the distance across the surface of the globe to another coordinate
+     * @param pin
+     */
+    distanceTo(pin: ILatLng): number;
+    /**
+     * Calculates the starting bearing across the surface of the globe from the current coordinate to the given coordinate
+     * @param pin
+     */
+    bearingTo(pin: ILatLng): number;
+    /**
+     * Returns a new coordinate at the given distance and bearing from this coordinate
+     * @param meters
+     * @param bearing
+     */
+    toTranslated(meters: number, bearing: number): LatLng;
+    /**
+     * Returns a new LatLng at the half-way point between this and the given LatLng.
+     * @param pin	The other coordinate.
+     * @throws {Error}	Either latitude or longitude is NaN
+     */
+    toBetween(pin: ILatLng): LatLng;
+    /**
+     * Creates a Point based on the given magnifier.
+     */
+    toRadians(magnifier?: number): Point;
+    /**
+     * Creates a square LatLngBounds centred around this LatLng.
+     * @param radius	The closest distance (in meters) from this coordinate to the edges of the new LatLngBounds.
+     */
+    toBounds(radius: number): LatLngBounds;
+}