@trakit/objects 0.0.9 → 0.0.10

package/API/Geography/StreetAddress.d.ts

@@ -0,0 +1,60 @@
+import { ISerializable } from "../Interfaces/ISerializable";
+import { JsonObject, nothing } from "../Types";
+import { IStreetAddress } from "./Interfaces";
+/**
+ * A road segment description
+*/
+export declare class StreetAddress implements IStreetAddress, ISerializable {
+    /**
+     *
+     * @param street
+     */
+    static fromJSON(json: IStreetAddress | JsonObject): StreetAddress;
+    /**
+     * House number.
+     */
+    number: string;
+    /**
+     * Full street name.
+     */
+    street: string;
+    /**
+     * City name.
+     */
+    city: string;
+    /**
+     * Region name.
+     */
+    region: string;
+    /**
+     * 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;
+    /**
+     * Indicates that there is a toll for the current road segment.
+     */
+    isToll: boolean;
+    constructor(number?: string | nothing, street?: string | nothing, city?: string | nothing, region?: string | nothing, province?: string | nothing, country?: string | nothing, postal?: string | nothing, isToll?: boolean | nothing);
+    /**
+     * Returns a text representation of this address.
+     * Returned strings cannot be converted back into {@link StreetAddress}
+     * objects, so don't use this for deserialization.
+     */
+    toString(): string;
+    /**
+     * Creates a literal of this {@link StreetAddress}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): IStreetAddress;
+}
+//# sourceMappingURL=StreetAddress.d.ts.map

package/API/Geometry/Functions.d.ts

@@ -0,0 +1,115 @@
+import { IPoint, IRadial, IRectangle } from './Interfaces';
+/**
+ * Calculates the starting angle (in degrees) between two Points using the top as zero.  Does not return negative values.
+ * @param starting	Starting coordinate
+ * @param ending	Other coordinate
+ * @returns A number between 0 and 360.
+ */
+export declare function POINT_ANGLE(starting: IPoint, ending: IPoint): number;
+/**
+ * Calculates the distance between two points using Pythagorean theorem.
+ * @param starting	Starting coordinate
+ * @param ending	Other coordinate
+ */
+export declare function POINT_DISTANCE(starting: IPoint, ending: IPoint): number;
+/**
+ * Sorts points by left-most, then by top-most.
+ */
+export declare function POINT_SORT(a: IPoint, b: IPoint): number;
+/**
+ * Calculates the vector which can be used to find the point based on the given direction and distance
+ * @param distance
+ * @param degrees
+ */
+export declare function POINT_VECTOR(distance: number, degrees: number): IPoint;
+/**
+ * Calculates the total length of the given path
+ * @param path	The array of points representing a path
+ * */
+export declare function PATH_LENGTH(path: IPoint[]): number;
+/**
+ * Calculates the orthogonal height of a triangle. The orthogonal height is
+ * calculated by drawing a line between the firstPoint and lastPoint, then
+ * getting the length of a line drawn up from the line to the midPoint at a 90
+ * degree angle.
+ * @param first		Left-most coordinate of the triangle
+ * @param mid		Top-most coordinate of the triangle
+ * @param last		Right-most coordinate of the triangle
+ */
+export declare function PATH_ORTHOGONAL(first: IPoint, mid: IPoint, last: IPoint): number;
+/**
+ * Performs a Douglas-Peucker path reduction based on the given tolerance.
+ * @param path	The array of points representing a path
+ * @param tolerance		Orthogonal height threshold for candidate points.  Default is 0.
+ * */
+export declare function PATH_PEUCKER(path: IPoint[], tolerance?: number): IPoint[];
+/**
+ * Calculates the total area occupied by the given path.  Treats non-closed paths as closed paths.
+ * @param path	The array of points representing a path
+ * */
+export declare function POLY_AREA(path: IPoint[]): number;
+/**
+ * A utility export function to determine if a given point is inside the given polygon path.
+ * @param poly	The array of points represents the path of the polygon.
+ * @param dot	The coordinate of the point to be checked.
+ * */
+export declare function POLY_CONTAINS(poly: IPoint[], dot: IPoint): boolean;
+/**
+ * Performs a Douglas-Peucker path reduction on a polygon for the given tolerance.
+ * The start/end points are variable and the end point is trimmed from the result.
+ * @param path	The array of points representing a path
+ * @param tolerance		Orthogonal height threshold for candidate points.  Default is 0.
+ * */
+export declare function POLY_PEUCKER(path: IPoint[], tolerance?: number): IPoint[];
+/**
+ * Wraps the given points into a polygonal path.  The given points do not need to be a path.  The returned path is not closed.
+ * @param points	The array of points on which to create the non-closed path
+ * @returns Non-closed path.
+ */
+export declare function POLY_WRAPPER(points: IPoint[]): IPoint[];
+/**
+ * Calculates the area of a circle based on the given radius.
+ * @param radius
+ * */
+export declare function RADIAL_AREA(radius: number): number;
+/**
+ * Solves the Minimum Enclosing Circle problem using Badoiu Clarkson's algorithm.
+ * @param points	The array of points on which to create the Radial
+ * @param iterations	The higher the iterations the slower and more accurate the Radial. Default is 10,000.
+ * */
+export declare function RADIAL_BADOIU_CLARKSON(points: IPoint[], iterations?: number): IRadial;
+/**
+ * Calculates the circumference of a circle based on the given radius.
+ * @param radius
+ * */
+export declare function RADIAL_CIRCUMFERENCE(radius: number): number;
+/**
+ * Creates an {@link IRectangle} which contains the given list of {@link IPoint}s.
+ * @param dots
+ */
+export declare function RECTANGLE_FROM_POINTS(dots: IPoint[]): IRectangle;
+/**
+ * Returns true if the given {@link Radial} overlaps the given {@link Rectangle}.
+ * @param circle
+ * @param rect
+ * */
+export declare function RADIAL_OVERLAP_RECTANGLE(circle: IRadial, rect: IRectangle): boolean;
+/**
+ *
+ * @param rect
+ */
+export declare function RECTANGLE_CENTRE(rect: IRectangle): IPoint;
+/**
+ * Determines if the given {@link IPoint} is contained by the given {@link Rectangle}.
+ * @param rect
+ * @param dot
+ * @returns
+ */
+export declare function RECTANGLE_CONTAINS_POINT(rect: IRectangle, dot: IPoint): boolean;
+/**
+ *
+ * @param rect
+ * @param clip
+ */
+export declare function RECTANGLE_TO_RADIAL(rect: IRectangle, clip: boolean): IRadial;
+//# sourceMappingURL=Functions.d.ts.map

package/API/Geometry/Interfaces.d.ts

@@ -0,0 +1,112 @@
+/**
+ * A coordinate on a flat surface.
+ */
+export interface IPoint {
+    /**
+     * Horizontal coordinate.
+     */
+    x: number;
+    /**
+     * Vertical coordinate.
+     */
+    y: number;
+}
+/**
+ * Returns true if the given point conforms to the {@link IPoint} interface.
+ * @param dot
+ * @returns
+ */
+export declare function IPoint_instanceOf(dot: any): dot is IPoint;
+/**
+ *
+ * @param dot
+ * @returns
+ */
+export declare function IPoint_clone(dot: IPoint): IPoint;
+/**
+ * A boundary on a flat surface based on a centre point and a radius.
+ */
+export interface IRadial extends IPoint {
+    /**
+     * Radius.
+     */
+    r: number;
+}
+/**
+ * The types used to extend a {@link Radial}'s radius.
+ */
+export type RadialExpansion = IPoint | IRadial | RadialExpansion[];
+/**
+ * Returns true if the given radial conforms to the {@link IRadial} interface.
+ * @param radial
+ * @returns
+ */
+export declare function IRadial_instanceOf(radial: any): radial is IRadial;
+/**
+ *
+ * @param circle
+ * @returns
+ */
+export declare function IRadial_clone(circle: IRadial): IRadial;
+/**
+ * A rectangular boundary on a flat surface.
+ */
+export interface IRectangle {
+    /**
+     * Left-most horizontal coordinate
+     */
+    left: number;
+    /**
+     * Highest vertical coordinate.
+     */
+    top: number;
+    /**
+     * Right-most horizontal coordinate
+     */
+    right: number;
+    /**
+     * Lowest vertical coordinate
+     */
+    bottom: number;
+}
+/**
+ * Returns true if the given rect conforms to the {@link Rectangle} interface.
+ * @param rect
+ */
+export declare function IRectangle_instanceOf(rect: any): rect is IRectangle;
+/**
+ *
+ * @param rect
+ * @returns
+ */
+export declare function IRectangle_clone(rect: IRectangle): IRectangle;
+/**
+ * The types used to extend a {@link Rectangle}'s edges.
+ */
+export type RectangleExpansion = IPoint | IRectangle | IRadial | RectangleExpansion[];
+/**
+ * Dimensions on a flat surface.
+ */
+export interface ISize {
+    /**
+     * Width.
+     */
+    width: number;
+    /**
+     * Height.
+     */
+    height: number;
+}
+/**
+ * Returns true if the given size conforms to the {@link Size} interface.
+ * @param size
+ * @returns
+ */
+export declare function ISize_instanceOf(size: any): size is ISize;
+/**
+ *
+ * @param size
+ * @returns
+ */
+export declare function ISize_clone(size: ISize): ISize;
+//# sourceMappingURL=Interfaces.d.ts.map

package/API/Geometry/Point.d.ts

@@ -0,0 +1,82 @@
+import { ISerializable } from '../Interfaces/ISerializable';
+import { JsonObject } from '../Types';
+import { IPoint } from './Interfaces';
+import { Radial } from './Radial';
+/**
+ * A coordinate on a flat surface.
+ */
+export declare class Point implements IPoint, ISerializable {
+    /**
+     * Returns a new {@link Radial} from the given object.
+     * @param json
+     */
+    static fromJSON(json: IPoint | JsonObject): Point;
+    /**
+     * Horizontal coordinate.
+     */
+    x: number;
+    /**
+     * Vertical coordinate.
+     */
+    y: number;
+    constructor(x: number, y: number);
+    /**
+     * Returns a string representation of this {@link Point}.
+     * @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 "x,y".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link Point}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): IPoint;
+    /**
+     * Creates a duplicate of this {@link Point}.
+     */
+    copy(): Point;
+    /**
+     * Compares this {@link Point} to another to see if they are equal.
+     * @param point	The other {@link Point} to compare.
+     * @param precision	The degree of precision to use; default is full precision.
+     */
+    isEqual(point: IPoint, precision?: number): point is IPoint;
+    /**
+     * Calculates the distance between two {@link Point}s.
+     * @param point	The other {@link Point} to compare
+     */
+    distanceTo(point: IPoint): number;
+    /**
+     * Calculates the angle (in degrees) to the given {@link Point}.
+     * @param point
+     */
+    angleTo(point: IPoint): number;
+    /**
+     * Updates this {@link Point} with the given angle and distance.
+     * @param distance
+     * @param degrees
+     */
+    translateTo(distance: number, degrees: number): this;
+    /**
+     * Updates this {@link Point} with the given offset.
+     * @param dot
+     */
+    offsetTo(dot: IPoint): this;
+    /**
+     * Creates a new {@link Point} at the given angle and distance.
+     * @param distance
+     * @param degrees
+     */
+    toTranslated(distance: number, degrees: number): Point;
+    /**
+     * Creates a new {@link Point} based on the given offset.
+     * @param offset
+     */
+    toOffset(offset: IPoint): Point;
+    /**
+     * Creates a new {@link Radial} based on the given radius.
+     * @param radius
+     */
+    toRadial(radius: number): Radial;
+}
+//# sourceMappingURL=Point.d.ts.map

package/API/Geometry/Radial.d.ts

@@ -0,0 +1,111 @@
+import { ISerializable } from '../Interfaces/ISerializable';
+import { JsonObject } from '../Types';
+import { IPoint, IRadial, RadialExpansion } from './Interfaces';
+import { Point } from './Point';
+import { Rectangle } from './Rectangle';
+import { Size } from './Size';
+/**
+ * A boundary on a flat surface based on a centre point and a radius.
+ */
+export declare class Radial implements IRadial, IPoint, ISerializable {
+    /**
+     * Returns a new {@link Radial} from the given object.
+     * @param object
+     */
+    static fromJSON(json: IRadial | JsonObject): Radial;
+    /**
+     * Left coordinate.
+     */
+    x: number;
+    /**
+     * Top coordinate.
+     */
+    y: number;
+    /**
+     * Radial distance.
+     */
+    r: number;
+    constructor(x?: number, y?: number, r?: number);
+    /**
+     * Returns a string representation of this {@link Radial}.
+     * @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 "x,y,r".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link Radial}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): IRadial;
+    /**
+     * Creates a duplicate of this {@link Radial}.
+     */
+    copy(): Radial;
+    /**
+     * Compares this Point to another to see if they are equal.
+     * @param circle	The other {@link IRadial} to compare
+     * @param precision	The degree of precision to use; default is full precision.
+     */
+    isEqual(circle: IRadial, precision?: number): boolean;
+    /**
+     * Determines if the given {@link IPoint} is contained by this Radial
+     * @param point
+     */
+    contains(point: IPoint): boolean;
+    /**
+     * Determines if the given {@link IRadial} is overlaps this {@link Radial} in any way
+     * @param circle
+     */
+    overlaps(circle: IRadial): boolean;
+    /**
+     * Returns the centre point representation.
+     */
+    getCentre(): Point;
+    /**
+     * Returns the {@link Size} of the diameter.
+     */
+    getSize(): Size;
+    /**
+     * Worker function that actually extends the boundary to envelop the given point(s)/boundary(s).
+     * @param object
+     */
+    __expander(object: RadialExpansion): void;
+    /**
+     * Extends the boundary to envelop the given point(s).
+     * @param object	The objects used to extend the radius.
+     */
+    extend(object: RadialExpansion): this;
+    /**
+     * Increases the boundary radius.
+     * @param length
+     */
+    grow(length: number): this;
+    /**
+     * Updates this {@link Radial} with the given angle and distance.
+     * @param distance
+     * @param degrees
+     */
+    translateTo(distance: number, degrees: number): this;
+    /**
+     * Updates this {@link Radial} with the given offset.
+     * @param dot
+     */
+    offsetTo(dot: IPoint): this;
+    /**
+     * Creates a new {@link Radial} at the given distance and direction.
+     * @param distance
+     * @param degrees
+     */
+    toTranslated(distance: number, degrees: number): Radial;
+    /**
+     * Creates a new {@link Radial} offset by the given amounts.
+     * @param point
+     */
+    toOffset(point: IPoint): Radial;
+    /**
+     * Converts this radial boundary into a {@link Rectangle}.
+     * @param clip	If true, [()], if false ([]).
+     */
+    toRectangle(clip?: boolean): Rectangle;
+}
+//# sourceMappingURL=Radial.d.ts.map

package/API/Geometry/Rectangle.d.ts

@@ -0,0 +1,160 @@
+import { IPoint, IRectangle, RectangleExpansion } from './Interfaces';
+import { Point } from './Point';
+import { Radial } from './Radial';
+import { Size } from './Size';
+/**
+ * A four-sided box on a flat surface.
+ */
+export declare class Rectangle implements IRectangle {
+    #private;
+    /**
+     * Returns a new {@link Radial} from the given object.
+     */
+    static fromJSON(rectangle: any): Rectangle;
+    /**
+     * Left-most horizontal coordinate
+     */
+    left: number;
+    /**
+     * Highest vertical coordinate.
+     */
+    top: number;
+    /**
+     * Right-most horizontal coordinate
+     */
+    right: number;
+    /**
+     * Lowest vertical coordinate
+     */
+    bottom: number;
+    /**
+     * The absolute width of this Rectangle.
+     */
+    get width(): number;
+    /**
+     * The absolute height of this Rectangle.
+     */
+    get height(): number;
+    constructor(left?: number | RectangleExpansion, top?: number | RectangleExpansion, right?: number | RectangleExpansion, bottom?: number | RectangleExpansion);
+    /**
+     * Validates the boundary and returns a string representation
+     * @param delimiter	The boundary is delimited by a comma (,) by default, but you can override with your own value (optional)
+     * @returns A string in the format of "left,top,right,bottom".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link Rectangle}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): IRectangle;
+    /**
+     * Compares this Rectangle to another to see if they are equal.
+     * @param rect	The other Rectangle to compare.
+     * @param precision	The degree of precision to use; default is full precision.
+     */
+    isEqual(rect: IRectangle, precision?: number): rect is IRectangle;
+    /**
+     * Checks to see if the bounds are valid (not inside-out).
+     */
+    isValid(): boolean;
+    /**
+     * Checks to see if the bounds are valid, and that the corners are different coordinates.
+     */
+    isEmpty(): boolean;
+    /**
+     * Determines if the given {@link IPoint} is contained by this {@link Rectangle}.
+     * @param dot
+     */
+    contains(dot: IPoint): boolean;
+    /**
+     * Determines if the given {@link IRectangle} is overlaps this {@link Rectangle} in any way
+     * @param rect
+     */
+    overlaps(rect: IRectangle): boolean;
+    /**
+     * Validates the boundary and creates a duplicate of this {@link Rectangle}.
+     */
+    copy(): Rectangle;
+    /**
+     * Returns the {@link Point} at the centre.
+     */
+    getCentre(): Point;
+    /**
+     * Validates the boundary and creates a {@link Size} representation.
+     */
+    getSize(): Size;
+    /**
+     * Returns the {@link Point} at the top-most/left-most corner.
+     */
+    getTopLeft(): Point;
+    /**
+     * Returns the {@link Point} at the top-most/right-most corner.
+     */
+    getTopRight(): Point;
+    /**
+     * Returns the {@link Point} at the bottom-most/left-most corner.
+     */
+    getBottomLeft(): Point;
+    /**
+     * Returns the {@link Point} at the bottom-most/right-most corner.
+     */
+    getBottomRight(): Point;
+    /**
+     * Validates the boundary by ensuring the top value is less than the bottom value,
+     * and the left value is less than the right value.
+     * Also adjusts the width and height values.
+     */
+    validate(): this;
+    /**
+     * Extends the boundary to envelop the given point(s) but does not automatically validate.
+     * This comes in efficient when doing many operations on a single {@link Rectangle}.
+     * @param object	The objects used to extend the boundary
+     */
+    expand(object: RectangleExpansion): this;
+    /**
+     * Extends the boundary to envelop the given point(s) and automatically validates
+     * @param object	The objects used to extend the boundary
+     */
+    extend(object: RectangleExpansion): this;
+    /**
+     * Increases the size of the boundary by the given width and height.
+     * If the direction contains the word "top", the {@link Rectangle#top} decreases by the given height.
+     * If the direction contains the word "bottom", the {@link Rectangle#bottom} increases by the given height.
+     * If the direction does not contain either "top" or "bottom", the {@link Rectangle#top} decreases by half the given height, and the {@link Rectangle#bottom} increases by half the given height.
+     * If the direction contains the word "left", the {@link Rectangle#left} decreases by the given width.
+     * If the direction contains the word "right", the {@link Rectangle#right} increases by the given width.
+     * If the direction does not contain either "left" or "right", the {@link Rectangle#left} decreases by half the given width, and the {@link Rectangle#right} increases by half the given height.
+     * @param width
+     * @param height
+     * @param direction
+     */
+    grow(width?: number, height?: number, direction?: string): this;
+    /**
+     * Updates this {@link Rectangle} with the given angle and distance.
+     * @param distance
+     * @param degrees
+     */
+    translateTo(distance: number, degrees: number): this;
+    /**
+     * Updates this {@link Rectangle} with the given offset.
+     * @param dot
+     */
+    offsetTo(dot: IPoint): this;
+    /**
+     * Creates a new {@link Rectangle} at the given angle and distance.
+     * @param distance
+     * @param degrees
+     */
+    toTranslated(distance: number, degrees: number): Rectangle;
+    /**
+     * Creates a new {@link Rectangle} offset by the given amounts.
+     * @param dot
+     */
+    toOffset(dot: IPoint): Rectangle;
+    /**
+     * Validates the boundary and returns a {@link Radial}.
+     * @param clip	If true, [()], if false ([]).
+     */
+    toRadial(clip?: boolean): Radial;
+}
+//# sourceMappingURL=Rectangle.d.ts.map

package/API/Geometry/Size.d.ts

@@ -0,0 +1,59 @@
+import { JsonObject } from '../Types';
+import { ISize } from './Interfaces';
+/**
+ * Dimensions on a flat surface.
+ */
+export declare class Size implements ISize {
+    /**
+     *
+     * @param json
+     * @returns
+     */
+    static fromJSON(json: ISize | JsonObject): Size;
+    /**
+     * Width.
+     */
+    width: number;
+    /**
+     * Height.
+     */
+    height: number;
+    constructor(width: number, height: number);
+    /**
+     * Returns a string representation.
+     * @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 "width,height".
+     */
+    toString(delimiter?: string): string;
+    /**
+     * Creates a literal of this {@link Size}.
+     * Used internally by {@link JSON.stringify}.
+     */
+    toJSON(): ISize;
+    /**
+     * Compares this Size to another to see if they are equal
+     * @param size		The other Size to compare
+     * @param precision	The degree of precision to use; default is full precision
+     */
+    isEqual(size: ISize, precision?: number): size is ISize;
+    /**
+     * Returns a new instance of a {@link Size} where the width and height are adjusted to the given ratios.
+     * If the second ratio is not given, then the first value is used for both.
+     * The ratios are given as a percentage between 0 and 1.
+     * To double the size of the Size, give a ratio of 2, and to shrink it to half size use 0.5.
+     * @param ratioX
+     * @param ratioY
+     */
+    resize(ratioX?: number, ratioY?: number): Size;
+    /**
+     * Returns a new {@link Size} where the width is the same as the given value, and the height is resized to preserve aspect ratio.
+     * @param width
+     */
+    resizeToWidth(width: number): Size;
+    /**
+     * Returns a new {@link Size} where the height is the same as the given value, and the width is resized to preserve aspect ratio.
+     * @param height
+     */
+    resizeToHeight(height: number): Size;
+}
+//# sourceMappingURL=Size.d.ts.map