@guillaume-docquier/tools-ts 6.4.1 → 6.6.0

package/README.md

@@ -122,9 +122,13 @@ Use these helpers for quick profiling.
 
 ### Measurements
 
-| Export | What it is                                                          | Use it when                                                  |
-| ------ | ------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `Time` | Represent a time value with a unit and contains conversion methods. | You want to represent time and abstract away the units used. |
+| Export                       | What it is                                                                        | Use it when                                                                    |
+| ---------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `Angle`, `UnitOfAngle`       | An angle measurement and its supported degree and radian units.                   | You need to represent angles and convert between degrees and radians.          |
+| `Time`, `UnitOfTime`         | A time measurement and its supported units, with conversion and arithmetic tools. | You need unit-aware durations or calculations across different time units.     |
+| `Distance`, `UnitOfDistance` | A distance measurement and its supported units, with conversion and comparison.   | You need unit-aware lengths, spatial comparisons, or distances between points. |
+| `Point2D`, `XY`              | A two-dimensional position and its plain coordinate-value shape.                  | You need 2D positions whose axes can use and convert between distance units.   |
+| `Point3D`, `XYZ`             | A three-dimensional position and its plain coordinate-value shape.                | You need 3D positions whose axes can use and convert between distance units.   |
 
 ### Date manipulations
 

package/dist/entry.tools-ts.d.ts

@@ -28,6 +28,10 @@ export { Sort } from "./Sort.js";
 export { createRng, type Rng, type Generator } from "./rng/rng.js";
 export { mulberry32Prng } from "./rng/mulberry32prng.js";
 export { Datetime } from "./Datetime.js";
+export { Angle, UnitOfAngle } from "./measurements/Angle.js";
 export { Time, UnitOfTime } from "./measurements/Time.js";
+export { Distance, UnitOfDistance } from "./measurements/Distance.js";
+export { Point2D, type XY } from "./measurements/Point2D.js";
+export { Point3D, type XYZ } from "./measurements/Point3D.js";
 export { Timer } from "./Timer.js";
 export { type Branded, branded } from "./Brand.js";

package/dist/entry.tools-ts.js

@@ -23,7 +23,11 @@ export { Sort } from "./Sort.js";
 export { createRng } from "./rng/rng.js";
 export { mulberry32Prng } from "./rng/mulberry32prng.js";
 export { Datetime } from "./Datetime.js";
+export { Angle, UnitOfAngle } from "./measurements/Angle.js";
 export { Time, UnitOfTime } from "./measurements/Time.js";
+export { Distance, UnitOfDistance } from "./measurements/Distance.js";
+export { Point2D } from "./measurements/Point2D.js";
+export { Point3D } from "./measurements/Point3D.js";
 export { Timer } from "./Timer.js";
 export { branded } from "./Brand.js";
 //# sourceMappingURL=entry.tools-ts.js.map

package/dist/entry.tools-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,SAAS,EAA4B,MAAM,cAAc,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgB,OAAO,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,SAAS,EAA4B,MAAM,cAAc,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,OAAO,EAAW,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAY,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgB,OAAO,EAAE,MAAM,YAAY,CAAA"}

package/dist/measurements/Angle.d.ts

@@ -0,0 +1,30 @@
+import type { Measurement } from "./Measurement.js";
+/**
+ * Represents the possible units to define an angle.
+ */
+export declare enum UnitOfAngle {
+    DEGREES = "degrees",
+    RADIANS = "radians"
+}
+/**
+ * Represents an angle with its unit.
+ */
+export type Angle = Measurement<UnitOfAngle>;
+/**
+ * A set of functions to work with angles.
+ */
+export declare const Angle: {
+    /**
+     * Creates an angle.
+     */
+    create(value: number, unit: UnitOfAngle): Angle;
+    /**
+     * Converts an angle to another unit.
+     * The provided angle is left untouched.
+     */
+    convert(angle: Readonly<Angle>, newUnit: UnitOfAngle): Angle;
+    /**
+     * Returns the value of the angle in the given unit.
+     */
+    in({ value, unit }: Readonly<Angle>, newUnit: UnitOfAngle): number;
+};

package/dist/measurements/Angle.js

@@ -0,0 +1,43 @@
+/**
+ * Represents the possible units to define an angle.
+ */
+export var UnitOfAngle;
+(function (UnitOfAngle) {
+    UnitOfAngle["DEGREES"] = "degrees";
+    UnitOfAngle["RADIANS"] = "radians";
+})(UnitOfAngle || (UnitOfAngle = {}));
+const RADIANS_PER_ANGLE = {
+    [UnitOfAngle.DEGREES]: Math.PI / 180,
+    [UnitOfAngle.RADIANS]: 1,
+};
+/**
+ * A set of functions to work with angles.
+ */
+export const Angle = {
+    /**
+     * Creates an angle.
+     */
+    create(value, unit) {
+        return { value, unit };
+    },
+    /**
+     * Converts an angle to another unit.
+     * The provided angle is left untouched.
+     */
+    convert(angle, newUnit) {
+        return {
+            value: Angle.in(angle, newUnit),
+            unit: newUnit,
+        };
+    },
+    /**
+     * Returns the value of the angle in the given unit.
+     */
+    in({ value, unit }, newUnit) {
+        if (unit === newUnit) {
+            return value;
+        }
+        return (value * RADIANS_PER_ANGLE[unit]) / RADIANS_PER_ANGLE[newUnit];
+    },
+};
+//# sourceMappingURL=Angle.js.map

package/dist/measurements/Angle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Angle.js","sourceRoot":"","sources":["../../src/measurements/Angle.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAN,IAAY,WAGX;AAHD,WAAY,WAAW;IACrB,kCAAmB,CAAA;IACnB,kCAAmB,CAAA;AACrB,CAAC,EAHW,WAAW,KAAX,WAAW,QAGtB;AAED,MAAM,iBAAiB,GAAgC;IACrD,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG;IACpC,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CACzB,CAAA;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;OAEG;IACH,MAAM,CAAC,KAAa,EAAE,IAAiB;QACrC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IACxB,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAsB,EAAE,OAAoB;QAClD,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC;YAC/B,IAAI,EAAE,OAAO;SACd,CAAA;IACH,CAAC;IAED;;OAEG;IACH,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAmB,EAAE,OAAoB;QACvD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,CAAC,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAA;IACvE,CAAC;CACF,CAAA"}

package/dist/measurements/Distance.d.ts

@@ -0,0 +1,61 @@
+import type { Measurement } from "./Measurement.js";
+import { Point3D } from "./Point3D.js";
+export declare enum UnitOfDistance {
+    METERS = "Meters",
+    MILLIMETERS = "Millimeters",
+    ASTRONOMICAL_UNITS = "Astronomical Units",
+    LIGHT_YEARS = "Light Years"
+}
+/**
+ * Represents a distance with its unit
+ */
+export type Distance = Measurement<UnitOfDistance>;
+/**
+ * A set of functions to work with Distances.
+ */
+export declare const Distance: {
+    /**
+     * Creates a distance.
+     * @param value The value for the distance.
+     * @param unit The unit for the distance.
+     */
+    create(value: number, unit: UnitOfDistance): Distance;
+    /**
+     * Converts a distance to another unit of distance.
+     * The provided distance is left untouched.
+     * @param distance The distance to convert.
+     * @param newUnit The unit to convert to.
+     * @returns A new Distance with the requested unit of distance.
+     */
+    convert(distance: Readonly<Distance>, newUnit: UnitOfDistance): Distance;
+    /**
+     * Returns the value of the distance in the given unit of distance.
+     * @param distance The distance to get the value of.
+     * @param newUnit The unit of distance to get the value of the distance in.
+     */
+    in({ value, unit }: Readonly<Distance>, newUnit: UnitOfDistance): number;
+    /**
+     * Determines if two distances are equal given a certain tolerance.
+     * The distances will be converted in the tolerance unit before comparison.
+     * @param distance1 The first distance to compare.
+     * @param distance2 The second distance to compare.
+     * @param tolerance The allowed tolerance.
+     */
+    areEqual(distance1: Readonly<Distance>, distance2: Readonly<Distance>, tolerance: Readonly<Distance>): boolean;
+    /**
+     * Computes the squared distance between two positions.
+     * @param position1 The first position.
+     * @param position2 The second position.
+     * @param unitOfReference The unit to use to compare the positions. This unit will also be the unit of the resulting Distance.
+     *   If not defined, a random unit will be used. Specifying your unit can help mitigate floating point errors.
+     */
+    betweenSquared(position1: Readonly<Point3D>, position2: Readonly<Point3D>, unitOfReference?: UnitOfDistance): Distance;
+    /**
+     * Computes the distance between two positions.
+     * @param position1 The first position.
+     * @param position2 The second position.
+     * @param unitOfReference The unit to use to compare the positions. This unit will also be the unit of the resulting Distance.
+     *   If not defined, a random unit will be used. Specifying your unit can help mitigate floating point errors.
+     */
+    between(position1: Readonly<Point3D>, position2: Readonly<Point3D>, unitOfReference?: UnitOfDistance): Distance;
+};

package/dist/measurements/Distance.js

@@ -0,0 +1,95 @@
+import { Point3D } from "./Point3D.js";
+export var UnitOfDistance;
+(function (UnitOfDistance) {
+    UnitOfDistance["METERS"] = "Meters";
+    UnitOfDistance["MILLIMETERS"] = "Millimeters";
+    UnitOfDistance["ASTRONOMICAL_UNITS"] = "Astronomical Units";
+    UnitOfDistance["LIGHT_YEARS"] = "Light Years";
+})(UnitOfDistance || (UnitOfDistance = {}));
+/**
+ * The definition of distances in meters.
+ * 1 millimeter is 0.001 meters.
+ * 1 astronomical unit is 149,597,870,700 meters.
+ * 1 light-year is 9,460,730,472,580,800 meters.
+ */
+const METERS_PER_DISTANCE = {
+    [UnitOfDistance.MILLIMETERS]: 0.001,
+    [UnitOfDistance.METERS]: 1,
+    [UnitOfDistance.ASTRONOMICAL_UNITS]: 149_597_870_700,
+    [UnitOfDistance.LIGHT_YEARS]: 9_460_730_472_580_800,
+};
+/**
+ * A set of functions to work with Distances.
+ */
+export const Distance = {
+    /**
+     * Creates a distance.
+     * @param value The value for the distance.
+     * @param unit The unit for the distance.
+     */
+    create(value, unit) {
+        return { value, unit };
+    },
+    /**
+     * Converts a distance to another unit of distance.
+     * The provided distance is left untouched.
+     * @param distance The distance to convert.
+     * @param newUnit The unit to convert to.
+     * @returns A new Distance with the requested unit of distance.
+     */
+    convert(distance, newUnit) {
+        return {
+            value: Distance.in(distance, newUnit),
+            unit: newUnit,
+        };
+    },
+    /**
+     * Returns the value of the distance in the given unit of distance.
+     * @param distance The distance to get the value of.
+     * @param newUnit The unit of distance to get the value of the distance in.
+     */
+    in({ value, unit }, newUnit) {
+        if (unit === newUnit) {
+            return value;
+        }
+        return (value * METERS_PER_DISTANCE[unit]) / METERS_PER_DISTANCE[newUnit];
+    },
+    /**
+     * Determines if two distances are equal given a certain tolerance.
+     * The distances will be converted in the tolerance unit before comparison.
+     * @param distance1 The first distance to compare.
+     * @param distance2 The second distance to compare.
+     * @param tolerance The allowed tolerance.
+     */
+    areEqual(distance1, distance2, tolerance) {
+        const difference = Distance.in(distance1, tolerance.unit) - Distance.in(distance2, tolerance.unit);
+        return Math.abs(difference) <= tolerance.value;
+    },
+    /**
+     * Computes the squared distance between two positions.
+     * @param position1 The first position.
+     * @param position2 The second position.
+     * @param unitOfReference The unit to use to compare the positions. This unit will also be the unit of the resulting Distance.
+     *   If not defined, a random unit will be used. Specifying your unit can help mitigate floating point errors.
+     */
+    betweenSquared(position1, position2, unitOfReference) {
+        const actualUnitOfReference = unitOfReference ?? position1.x.unit;
+        const xyz1 = Point3D.in(position1, actualUnitOfReference);
+        const xyz2 = Point3D.in(position2, actualUnitOfReference);
+        const distanceValue = Math.pow(xyz1.x - xyz2.x, 2) + Math.pow(xyz1.y - xyz2.y, 2) + Math.pow(xyz1.z - xyz2.z, 2);
+        return Distance.create(distanceValue, actualUnitOfReference);
+    },
+    /**
+     * Computes the distance between two positions.
+     * @param position1 The first position.
+     * @param position2 The second position.
+     * @param unitOfReference The unit to use to compare the positions. This unit will also be the unit of the resulting Distance.
+     *   If not defined, a random unit will be used. Specifying your unit can help mitigate floating point errors.
+     */
+    between(position1, position2, unitOfReference) {
+        const distance = Distance.betweenSquared(position1, position2, unitOfReference);
+        distance.value = Math.sqrt(distance.value);
+        return distance;
+    },
+};
+//# sourceMappingURL=Distance.js.map

package/dist/measurements/Distance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Distance.js","sourceRoot":"","sources":["../../src/measurements/Distance.ts"],"names":[],"mappings":"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"}

package/dist/measurements/Point2D.d.ts

@@ -0,0 +1,34 @@
+import { Distance, UnitOfDistance } from "./Distance.js";
+/**
+ * Represents a position in 2D space.
+ */
+export type Point2D = {
+    x: Distance;
+    y: Distance;
+};
+export type XY = {
+    x: Distance["value"];
+    y: Distance["value"];
+};
+/**
+ * A set of functions to work with 2D positions.
+ */
+export declare const Point2D: {
+    /**
+     * Builds a position from XY values with the same unit.
+     */
+    create({ x, y }: Readonly<XY>, unit: UnitOfDistance): Point2D;
+    /**
+     * Converts x and y to one unit or to the matching units of another position.
+     * The provided position is left untouched.
+     */
+    convert({ x, y }: Readonly<Point2D>, unit: Readonly<Point2D> | UnitOfDistance): Point2D;
+    /**
+     * Converts x and y to the given unit and returns their values.
+     */
+    in({ x, y }: Readonly<Point2D>, newUnit: UnitOfDistance): XY;
+    /**
+     * Determines if two positions are within an inclusive distance tolerance.
+     */
+    areEqual(position1: Readonly<Point2D>, position2: Readonly<Point2D>, tolerance: Readonly<Distance>): boolean;
+};

package/dist/measurements/Point2D.js

@@ -0,0 +1,51 @@
+import { TypeGuard } from "../TypeGuard.js";
+import { Distance, UnitOfDistance } from "./Distance.js";
+/**
+ * A set of functions to work with 2D positions.
+ */
+export const Point2D = {
+    /**
+     * Builds a position from XY values with the same unit.
+     */
+    create({ x, y }, unit) {
+        return {
+            x: Distance.create(x, unit),
+            y: Distance.create(y, unit),
+        };
+    },
+    /**
+     * Converts x and y to one unit or to the matching units of another position.
+     * The provided position is left untouched.
+     */
+    convert({ x, y }, unit) {
+        if (TypeGuard.isEnumMember(UnitOfDistance, unit)) {
+            return {
+                x: Distance.convert(x, unit),
+                y: Distance.convert(y, unit),
+            };
+        }
+        return {
+            x: Distance.convert(x, unit.x.unit),
+            y: Distance.convert(y, unit.y.unit),
+        };
+    },
+    /**
+     * Converts x and y to the given unit and returns their values.
+     */
+    in({ x, y }, newUnit) {
+        return {
+            x: Distance.in(x, newUnit),
+            y: Distance.in(y, newUnit),
+        };
+    },
+    /**
+     * Determines if two positions are within an inclusive distance tolerance.
+     */
+    areEqual(position1, position2, tolerance) {
+        const xy1 = Point2D.in(position1, tolerance.unit);
+        const xy2 = Point2D.in(position2, tolerance.unit);
+        const distance = Math.hypot(xy1.x - xy2.x, xy1.y - xy2.y);
+        return distance <= tolerance.value;
+    },
+};
+//# sourceMappingURL=Point2D.js.map

package/dist/measurements/Point2D.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Point2D.js","sourceRoot":"","sources":["../../src/measurements/Point2D.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAexD;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAgB,EAAE,IAAoB;QACjD,OAAO;YACL,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC;YAC3B,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC;SAC5B,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAqB,EAAE,IAAwC;QAC3E,IAAI,SAAS,CAAC,YAAY,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC;YACjD,OAAO;gBACL,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC;gBAC5B,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC;aAC7B,CAAA;QACH,CAAC;QAED,OAAO;YACL,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACnC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;SACpC,CAAA;IACH,CAAC;IAED;;OAEG;IACH,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAqB,EAAE,OAAuB;QACrD,OAAO;YACL,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC;YAC1B,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC;SAC3B,CAAA;IACH,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,SAA4B,EAAE,SAA4B,EAAE,SAA6B;QAChG,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;QACjD,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;QAEzD,OAAO,QAAQ,IAAI,SAAS,CAAC,KAAK,CAAA;IACpC,CAAC;CACF,CAAA"}

package/dist/measurements/Point3D.d.ts

@@ -0,0 +1,49 @@
+import { Distance, UnitOfDistance } from "./Distance.js";
+/**
+ * Represents a position in 3D space
+ */
+export type Point3D = {
+    x: Distance;
+    y: Distance;
+    z: Distance;
+};
+export type XYZ = {
+    x: Distance["value"];
+    y: Distance["value"];
+    z: Distance["value"];
+};
+/**
+ * A set of functions to work with Positions.
+ */
+export declare const Point3D: {
+    /**
+     * Builds a position from XYZ with the same unit.
+     * @param x The x value
+     * @param y The y value
+     * @param z The z value
+     * @param unit The unit to use for all values
+     */
+    create({ x, y, z }: Readonly<XYZ>, unit: UnitOfDistance): Point3D;
+    /**
+     * Converts x, y, and z to the given unit.
+     * The unit can be a UnitOfDistance, or another Position.
+     * When the unit is a Position, each value will be converted to the matching Position's unit.
+     * @param position The position to convert.
+     * @param unit The unit(s) to convert to.
+     */
+    convert({ x, y, z }: Readonly<Point3D>, unit: Readonly<Point3D> | UnitOfDistance): Point3D;
+    /**
+     * Converts x, y, and z to the given unit and returns the values
+     * @param position The position to convert.
+     * @param newUnit The new unit to convert to.
+     */
+    in({ x, y, z }: Readonly<Point3D>, newUnit: UnitOfDistance): XYZ;
+    /**
+     * Determines if two positions are equal given a certain tolerance.
+     * The positions will be converted in the tolerance unit before comparison.
+     * @param position1 The first position to compare.
+     * @param position2 The second position to compare.
+     * @param tolerance The allowed tolerance.
+     */
+    areEqual(position1: Readonly<Point3D>, position2: Readonly<Point3D>, tolerance: Readonly<Distance>): boolean;
+};

package/dist/measurements/Point3D.js

@@ -0,0 +1,66 @@
+import { TypeGuard } from "../TypeGuard.js";
+import { Distance, UnitOfDistance } from "./Distance.js";
+/**
+ * A set of functions to work with Positions.
+ */
+export const Point3D = {
+    /**
+     * Builds a position from XYZ with the same unit.
+     * @param x The x value
+     * @param y The y value
+     * @param z The z value
+     * @param unit The unit to use for all values
+     */
+    create({ x, y, z }, unit) {
+        return {
+            x: { value: x, unit },
+            y: { value: y, unit },
+            z: { value: z, unit },
+        };
+    },
+    /**
+     * Converts x, y, and z to the given unit.
+     * The unit can be a UnitOfDistance, or another Position.
+     * When the unit is a Position, each value will be converted to the matching Position's unit.
+     * @param position The position to convert.
+     * @param unit The unit(s) to convert to.
+     */
+    convert({ x, y, z }, unit) {
+        if (TypeGuard.isEnumMember(UnitOfDistance, unit)) {
+            return {
+                x: Distance.convert(x, unit),
+                y: Distance.convert(y, unit),
+                z: Distance.convert(z, unit),
+            };
+        }
+        return {
+            x: Distance.convert(x, unit.x.unit),
+            y: Distance.convert(y, unit.y.unit),
+            z: Distance.convert(z, unit.z.unit),
+        };
+    },
+    /**
+     * Converts x, y, and z to the given unit and returns the values
+     * @param position The position to convert.
+     * @param newUnit The new unit to convert to.
+     */
+    in({ x, y, z }, newUnit) {
+        return {
+            x: Distance.in(x, newUnit),
+            y: Distance.in(y, newUnit),
+            z: Distance.in(z, newUnit),
+        };
+    },
+    /**
+     * Determines if two positions are equal given a certain tolerance.
+     * The positions will be converted in the tolerance unit before comparison.
+     * @param position1 The first position to compare.
+     * @param position2 The second position to compare.
+     * @param tolerance The allowed tolerance.
+     */
+    areEqual(position1, position2, tolerance) {
+        const distance = Distance.between(position1, position2, tolerance.unit);
+        return Math.abs(distance.value) <= tolerance.value;
+    },
+};
+//# sourceMappingURL=Point3D.js.map

package/dist/measurements/Point3D.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Point3D.js","sourceRoot":"","sources":["../../src/measurements/Point3D.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAiBxD;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAiB,EAAE,IAAoB;QACrD,OAAO;YACL,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE;YACrB,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE;YACrB,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE;SACtB,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAqB,EAAE,IAAwC;QAC9E,IAAI,SAAS,CAAC,YAAY,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC;YACjD,OAAO;gBACL,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC;gBAC5B,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC;gBAC5B,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC;aAC7B,CAAA;QACH,CAAC;QAED,OAAO;YACL,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACnC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACnC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;SACpC,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAqB,EAAE,OAAuB;QACxD,OAAO;YACL,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC;YAC1B,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC;YAC1B,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC;SAC3B,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,SAA4B,EAAE,SAA4B,EAAE,SAA6B;QAChG,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;QAEvE,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,KAAK,CAAA;IACpD,CAAC;CACF,CAAA"}

package/dist/measurements/Time.d.ts

@@ -24,19 +24,19 @@ export declare const Time: {
      * @param newUnit The new unit to convert to.
      * @returns A new Time with the requested unit of time.
      */
-    convert(time: Time, newUnit: UnitOfTime): Time;
+    convert(time: Readonly<Time>, newUnit: UnitOfTime): Time;
     /**
      * Returns the value of the time in the given unit of time.
      * @param time The time to get the value of.
      * @param newUnit The unit of time to get the value of the time in.
      */
-    in(time: Time, newUnit: UnitOfTime): number;
+    in(time: Readonly<Time>, newUnit: UnitOfTime): number;
     /**
      * Adds 2 times together. The unit of the first time will be used.
      */
-    add(timeA: Time, timeB: Time): Time;
+    add(timeA: Readonly<Time>, timeB: Readonly<Time>): Time;
     /**
      * Subtracts 2 times. The unit of the first time will be used.
      */
-    subtract(timeA: Time, timeB: Time): Time;
+    subtract(timeA: Readonly<Time>, timeB: Readonly<Time>): Time;
 };

package/dist/measurements/Time.js.map

@@ -1 +1 @@
-{"version":3,"file":"Time.js","sourceRoot":"","sources":["../../src/measurements/Time.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACpB,2CAA6B,CAAA;IAC7B,iCAAmB,CAAA;IACnB,iCAAmB,CAAA;IACnB,6BAAe,CAAA;AACjB,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB;AAED;;;GAGG;AACH,MAAM,gBAAgB,GAA+B;IACnD,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,IAAI;IAC/B,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACvB,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE;IAC5B,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE;CAChC,CAAA;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,MAAM,EAAE,CAAC,KAAa,EAAE,IAAgB,EAAQ,EAAE;QAChD,OAAO;YACL,KAAK;YACL,IAAI;SACL,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,IAAU,EAAE,OAAmB;QACrC,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC;YAC7B,IAAI,EAAE,OAAO;SACd,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,IAAU,EAAE,OAAmB;QAChC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/E,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,KAAW,EAAE,KAAW;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1E,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAW,EAAE,KAAW;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1E,CAAC;CACF,CAAA"}
+{"version":3,"file":"Time.js","sourceRoot":"","sources":["../../src/measurements/Time.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACpB,2CAA6B,CAAA;IAC7B,iCAAmB,CAAA;IACnB,iCAAmB,CAAA;IACnB,6BAAe,CAAA;AACjB,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB;AAED;;;GAGG;AACH,MAAM,gBAAgB,GAA+B;IACnD,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,IAAI;IAC/B,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACvB,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE;IAC5B,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE;CAChC,CAAA;AAOD;;GAEG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,MAAM,EAAE,CAAC,KAAa,EAAE,IAAgB,EAAQ,EAAE;QAChD,OAAO;YACL,KAAK;YACL,IAAI;SACL,CAAA;IACH,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,IAAoB,EAAE,OAAmB;QAC/C,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC;YAC7B,IAAI,EAAE,OAAO;SACd,CAAA;IACH,CAAC;IAED;;;;OAIG;IACH,EAAE,CAAC,IAAoB,EAAE,OAAmB;QAC1C,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/E,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,KAAqB,EAAE,KAAqB;QAC9C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1E,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAqB,EAAE,KAAqB;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;IAC1E,CAAC;CACF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaume-docquier/tools-ts",
-  "version": "6.4.1",
+  "version": "6.6.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",
@@ -40,10 +40,10 @@
     "husky": "^9.1.7",
     "jiti": "^2.7.0",
     "lint-staged": "^16.4.0",
-    "oxfmt": ">=0.61.0",
-    "oxlint": "^1.76.0",
+    "oxfmt": ">=0.62.0",
+    "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
-    "semantic-release": "^25.0.8",
+    "semantic-release": "^25.0.9",
     "typescript": "~7.0.2",
     "vite": "^8.2.0",
     "vitest": "^4.1.10",