@zthun/helpful-fn 6.0.0 → 6.2.0

package/dist/geometry/quadrilateral-corners.d.mts

@@ -0,0 +1,152 @@
+/**
+ * An object that describes 4 corner values of a quadrilateral.
+ *
+ * This object is almost identical in functionality to a quadrilateral,
+ * but is mostly useful for semantics.
+ *
+ * @param T -
+ *        The type of data to associate to each corner.
+ */
+export interface IZQuadrilateralCorners<T = number> {
+    bottomLeft: T;
+    bottomRight: T;
+    topLeft: T;
+    topRight: T;
+}
+/**
+ * A type that describes quadrilateral corners on the vertical axis.
+ */
+type ZCornersVertical<T> = {
+    bottom?: T;
+    top?: T;
+};
+/**
+ * A type that describes quadrilateral corners on the horizontal axis.
+ */
+type ZCornersHorizontal<T> = {
+    left?: T;
+    right?: T;
+};
+/**
+ * An value that a corners object can be built upon.
+ */
+export type ZQuadrilateralCornersLike<T = number> = T | ZCornersVertical<T> | ZCornersHorizontal<T> | Partial<IZQuadrilateralCorners<T>> | null | undefined;
+/**
+ * An object that can be used to build an {@link IZQuadrilateralCorners} object.
+ *
+ * @param T -
+ *        The type of data to associate to each corner.
+ */
+export declare class ZQuadrilateralCornersBuilder<T = number> {
+    private _corners;
+    constructor(start: T);
+    /**
+     * Sets the bottom left corner value.
+     *
+     * @param value -
+     *        The value to set.
+     *
+     * @returns
+     *        This object.
+     */
+    bottomLeft(value: T): this;
+    /**
+     * Sets the bottom right corner value.
+     *
+     * @param value -
+     *        The value to set.
+     *
+     * @returns
+     *        This object.
+     */
+    bottomRight(value: T): this;
+    /**
+     * Sets the top left corner value.
+     *
+     * @param value -
+     *        The value to set.
+     *
+     * @returns
+     *        This object.
+     */
+    topLeft(value: T): this;
+    /**
+     * Sets the top right corner value.
+     *
+     * @param value -
+     *        The value to set.
+     *
+     * @returns
+     *        This object.
+     */
+    topRight(value: T): this;
+    /**
+     * Sets the bottom left and bottom right values.
+     *
+     * @param value -
+     *        The value for bottom left and bottom right.
+     *
+     * @returns
+     *        This object.
+     */
+    bottom(value: T): this;
+    /**
+     * Sets the bottom left and top left values.
+     *
+     * @param value -
+     *        The value for bottom left and top left.
+     *
+     * @returns
+     *        This object.
+     */
+    left(value: T): this;
+    /**
+     * Sets the bottom right and top right values.
+     *
+     * @param value -
+     *        The value for bottom right and top right.
+     *
+     * @returns
+     *        This object.
+     */
+    right(value: T): this;
+    /**
+     * Sets the top left and top right  values.
+     *
+     * @param value -
+     *        The value for top left and top right.
+     *
+     * @returns
+     *        This object.
+     */
+    top(value: T): this;
+    /**
+     * Sets the corner values based on an object that
+     * describes a set of quadrilateral corners.
+     *
+     * @param other -
+     *        The object that describes the corners.
+     *
+     * @returns
+     *        This object.
+     */
+    from(other: ZQuadrilateralCornersLike<T>): this;
+    /**
+     * Copies another corners object into this builder.
+     *
+     * @param other -
+     *        The corners object to copy.
+     *
+     * @returns
+     *        This object.
+     */
+    copy(other: IZQuadrilateralCorners<T>): this;
+    /**
+     * Builds the corners.
+     *
+     * @returns
+     *        The built corners.
+     */
+    build(): IZQuadrilateralCorners<T>;
+}
+export {};

package/dist/geometry/quadrilateral.d.mts

@@ -1,3 +1,4 @@
+import { IZPoint2d } from './point.mjs';
 /**
  * Represents a object of 4 side values.
  *
@@ -22,6 +23,14 @@ export interface IZQuadrilateral<T = number> {
      */
     top: T;
 }
+/**
+ * Represents an object that can describe a quadrilateral.
+ *
+ * Note that there will be limitations on what you can describe
+ * when building Quadrilaterals of Quadrilaterals, or Quadrilaterals
+ * of Point2d's which is not supported and has undefined behavior.
+ */
+export type ZQuadrilateralLike<T = number> = T | Partial<IZPoint2d<T>> | Partial<IZQuadrilateral<T>> | null | undefined;
 /**
  * Represents a builder for a quadrilateral object.
  */
@@ -94,6 +103,20 @@ export declare class ZQuadrilateralBuilder<T = number> {
      *        This object.
      */
     y(y: T): this;
+    /**
+     * Constructs a full quadrilateral from an object that describes a quadrilateral.
+     *
+     * Note the limitations of this method.  If T is of type Quadrilateral or Point2d,
+     * then this method's behavior is undefined and it will most likely build a
+     * corrupt object.
+     *
+     * @param other -
+     *        The object to build from.
+     *
+     * @returns
+     *        This object.
+     */
+    from(other: ZQuadrilateralLike<T>): this;
     /**
      * Copies another quadrilateral object into the current instance.
      *

package/dist/index.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const uuid = require("uuid");
+const lodashEs = require("lodash-es");
 var ZVerticalAnchor = /* @__PURE__ */ ((ZVerticalAnchor2) => {
   ZVerticalAnchor2["Top"] = "top";
   ZVerticalAnchor2["Middle"] = "middle";
@@ -121,6 +122,189 @@ function firstTruthy(fallback, first, ...remaining) {
     ...remaining
   );
 }
+class ZQuadrilateralCornersBuilder {
+  constructor(start) {
+    this._corners = {
+      bottomLeft: start,
+      bottomRight: start,
+      topLeft: start,
+      topRight: start
+    };
+  }
+  /**
+   * Sets the bottom left corner value.
+   *
+   * @param value -
+   *        The value to set.
+   *
+   * @returns
+   *        This object.
+   */
+  bottomLeft(value) {
+    this._corners.bottomLeft = value;
+    return this;
+  }
+  /**
+   * Sets the bottom right corner value.
+   *
+   * @param value -
+   *        The value to set.
+   *
+   * @returns
+   *        This object.
+   */
+  bottomRight(value) {
+    this._corners.bottomRight = value;
+    return this;
+  }
+  /**
+   * Sets the top left corner value.
+   *
+   * @param value -
+   *        The value to set.
+   *
+   * @returns
+   *        This object.
+   */
+  topLeft(value) {
+    this._corners.topLeft = value;
+    return this;
+  }
+  /**
+   * Sets the top right corner value.
+   *
+   * @param value -
+   *        The value to set.
+   *
+   * @returns
+   *        This object.
+   */
+  topRight(value) {
+    this._corners.topRight = value;
+    return this;
+  }
+  /**
+   * Sets the bottom left and bottom right values.
+   *
+   * @param value -
+   *        The value for bottom left and bottom right.
+   *
+   * @returns
+   *        This object.
+   */
+  bottom(value) {
+    return this.bottomLeft(value).bottomRight(value);
+  }
+  /**
+   * Sets the bottom left and top left values.
+   *
+   * @param value -
+   *        The value for bottom left and top left.
+   *
+   * @returns
+   *        This object.
+   */
+  left(value) {
+    return this.topLeft(value).bottomLeft(value);
+  }
+  /**
+   * Sets the bottom right and top right values.
+   *
+   * @param value -
+   *        The value for bottom right and top right.
+   *
+   * @returns
+   *        This object.
+   */
+  right(value) {
+    return this.bottomRight(value).topRight(value);
+  }
+  /**
+   * Sets the top left and top right  values.
+   *
+   * @param value -
+   *        The value for top left and top right.
+   *
+   * @returns
+   *        This object.
+   */
+  top(value) {
+    return this.topLeft(value).topRight(value);
+  }
+  /**
+   * Sets the corner values based on an object that
+   * describes a set of quadrilateral corners.
+   *
+   * @param other -
+   *        The object that describes the corners.
+   *
+   * @returns
+   *        This object.
+   */
+  from(other) {
+    function isVerticals(candidate) {
+      return candidate != null && (Object.prototype.hasOwnProperty.call(candidate, "bottom") || Object.prototype.hasOwnProperty.call(candidate, "top"));
+    }
+    function isHorizontals(candidate) {
+      return candidate != null && (Object.prototype.hasOwnProperty.call(candidate, "left") || Object.prototype.hasOwnProperty.call(candidate, "right"));
+    }
+    function isCorners(candidate) {
+      return candidate != null && (Object.prototype.hasOwnProperty.call(candidate, "bottomLeft") || Object.prototype.hasOwnProperty.call(candidate, "bottomRight") || Object.prototype.hasOwnProperty.call(candidate, "topLeft") || Object.prototype.hasOwnProperty.call(candidate, "topRight"));
+    }
+    const { bottomLeft, bottomRight, topLeft, topRight } = this._corners;
+    if (isCorners(other)) {
+      this._corners.bottomLeft = firstDefined(bottomLeft, other.bottomLeft);
+      this._corners.bottomRight = firstDefined(bottomRight, other.bottomRight);
+      this._corners.topLeft = firstDefined(topLeft, other.topLeft);
+      this._corners.topRight = firstDefined(topRight, other.topRight);
+      return this;
+    }
+    if (isVerticals(other)) {
+      this._corners.bottomLeft = firstDefined(bottomLeft, other.bottom);
+      this._corners.bottomRight = firstDefined(bottomRight, other.bottom);
+      this._corners.topLeft = firstDefined(topLeft, other.top);
+      this._corners.topRight = firstDefined(topRight, other.top);
+      return this;
+    }
+    if (isHorizontals(other)) {
+      this._corners.bottomLeft = firstDefined(bottomLeft, other.left);
+      this._corners.bottomRight = firstDefined(bottomRight, other.right);
+      this._corners.topLeft = firstDefined(topLeft, other.left);
+      this._corners.topRight = firstDefined(topRight, other.right);
+      return this;
+    }
+    if (typeof other === "object" && lodashEs.isEmpty(other)) {
+      return this;
+    }
+    this._corners.bottomLeft = firstDefined(bottomLeft, other);
+    this._corners.bottomRight = firstDefined(bottomRight, other);
+    this._corners.topLeft = firstDefined(topLeft, other);
+    this._corners.topRight = firstDefined(topRight, other);
+    return this;
+  }
+  /**
+   * Copies another corners object into this builder.
+   *
+   * @param other -
+   *        The corners object to copy.
+   *
+   * @returns
+   *        This object.
+   */
+  copy(other) {
+    this._corners = structuredClone(other);
+    return this;
+  }
+  /**
+   * Builds the corners.
+   *
+   * @returns
+   *        The built corners.
+   */
+  build() {
+    return structuredClone(this._corners);
+  }
+}
 class ZQuadrilateralBuilder {
   /**
    * Initializes a new instance of this object.
@@ -212,6 +396,49 @@ class ZQuadrilateralBuilder {
   y(y) {
     return this.bottom(y).top(y);
   }
+  /**
+   * Constructs a full quadrilateral from an object that describes a quadrilateral.
+   *
+   * Note the limitations of this method.  If T is of type Quadrilateral or Point2d,
+   * then this method's behavior is undefined and it will most likely build a
+   * corrupt object.
+   *
+   * @param other -
+   *        The object to build from.
+   *
+   * @returns
+   *        This object.
+   */
+  from(other) {
+    function isPoint2d(candidate) {
+      return candidate != null && (Object.prototype.hasOwnProperty.call(candidate, "x") || Object.prototype.hasOwnProperty.call(candidate, "y"));
+    }
+    function isQuadrilateral(candidate) {
+      return candidate != null && (Object.prototype.hasOwnProperty.call(candidate, "bottom") || Object.prototype.hasOwnProperty.call(candidate, "left") || Object.prototype.hasOwnProperty.call(candidate, "right") || Object.prototype.hasOwnProperty.call(candidate, "top"));
+    }
+    if (isQuadrilateral(other)) {
+      this._quad.bottom = firstDefined(this._quad.bottom, other.bottom);
+      this._quad.left = firstDefined(this._quad.left, other.left);
+      this._quad.right = firstDefined(this._quad.right, other.right);
+      this._quad.top = firstDefined(this._quad.top, other.top);
+      return this;
+    }
+    if (isPoint2d(other)) {
+      this._quad.bottom = firstDefined(this._quad.bottom, other.y);
+      this._quad.left = firstDefined(this._quad.left, other.x);
+      this._quad.right = firstDefined(this._quad.right, other.x);
+      this._quad.top = firstDefined(this._quad.top, other.y);
+      return this;
+    }
+    if (typeof other === "object" && lodashEs.isEmpty(other)) {
+      return this;
+    }
+    this._quad.bottom = firstDefined(this._quad.bottom, other);
+    this._quad.left = firstDefined(this._quad.left, other);
+    this._quad.right = firstDefined(this._quad.right, other);
+    this._quad.top = firstDefined(this._quad.top, other);
+    return this;
+  }
   /**
    * Copies another quadrilateral object into the current instance.
    *
@@ -497,6 +724,7 @@ exports.ZDeserializeTry = ZDeserializeTry;
 exports.ZHorizontalAnchor = ZHorizontalAnchor;
 exports.ZOrientation = ZOrientation;
 exports.ZQuadrilateralBuilder = ZQuadrilateralBuilder;
+exports.ZQuadrilateralCornersBuilder = ZQuadrilateralCornersBuilder;
 exports.ZRectangle = ZRectangle;
 exports.ZSerializeJson = ZSerializeJson;
 exports.ZVerticalAnchor = ZVerticalAnchor;