@guillaume-docquier/tools-ts 6.5.0 → 6.6.0

package/README.md

@@ -122,10 +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.      |
-| `Distance` | Represent a distance value with a unit and contains conversion and comparison methods. | You want to represent distances 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,8 +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 { Point3D } from "./measurements/Point3D.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,8 +23,10 @@ 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";

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,QAAQ,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AACnD,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/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

@@ -7,11 +7,11 @@ export type Point3D = {
     y: Distance;
     z: Distance;
 };
-interface XYZ {
+export type XYZ = {
     x: Distance["value"];
     y: Distance["value"];
     z: Distance["value"];
-}
+};
 /**
  * A set of functions to work with Positions.
  */
@@ -47,4 +47,3 @@ export declare const Point3D: {
      */
     areEqual(position1: Readonly<Point3D>, position2: Readonly<Point3D>, tolerance: Readonly<Distance>): boolean;
 };
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaume-docquier/tools-ts",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",