@tempots/std 0.11.0 → 0.13.0

package/number.d.ts

@@ -1,101 +1,391 @@
-export declare const TOLERANCE = 0.0001;
 /**
   Constant value employed to see if two `number` values are very close.
 **/
 export declare const EPSILON = 1e-9;
 /**
-Returns the angular distance between 2 angles.
-**/
+ * Calculates the minimum difference between two angles in degrees.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param turn - The total number of degrees in a full turn. Default is 360.0.
+ * @returns The difference between the two angles.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * angleDifference(0, 90) // returns 90
+ * angleDifference(90, 0) // returns -90
+ * angleDifference(0, 270) // returns -90
+ * angleDifference(270, 0) // returns 90
+ * ```
+ */
 export declare function angleDifference(a: number, b: number, turn?: number): number;
 /**
-Rounds a number up to the specified number of decimals.
-**/
+ * Rounds a number up to the specified number of decimals.
+ *
+ * @param v - The number to round up.
+ * @param decimals - The number of decimals to round up to.
+ * @returns The rounded up number.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * ceilTo(1.234, 2) // returns 1.24
+ * ceilTo(1.234, 1) // returns 1.3
+ * ceilTo(1.234, 0) // returns 2
+ * ```
+ */
 export declare function ceilTo(v: number, decimals: number): number;
 /**
-`clamp` restricts a value within the specified range.
-```ts
-log(clamp(1.3, 0, 1)) // prints 1
-log(clamp(0.8, 0, 1)) // prints 0.8
-log(clamp(-0.5, 0, 1)) // prints 0.0
-```
-**/
+ * `clamp` restricts a value within the specified range.
+ *
+ * @param value - The value to clamp.
+ * @param min - The minimum value.
+ * @param max - The maximum value.
+ * @returns The clamped value.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * clamp(1.3, 0, 1) // returns 1
+ * clamp(0.8, 0, 1) // returns 0.8
+ * clamp(-0.5, 0, 1) // returns 0.0
+ * ```
+ **/
 export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Clamps a number to a specified range and returns an integer value.
+ *
+ * @param value - The number to clamp.
+ * @param min - The minimum value of the range.
+ * @param max - The maximum value of the range.
+ * @returns The clamped integer value.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * clampInt(5, 0, 10) // returns 5
+ * clampInt(15, 0, 10) // returns 10
+ * clampInt(-5, 0, 10) // returns 0
+ * ```
+ **/
 export declare function clampInt(value: number, min: number, max: number): number;
 /**
-Like clamp but you only pass one argument (`max`) that is used as the upper limit
-and the opposite (additive inverse or `-max`) as the lower limit.
-**/
+ * Like clamp but you only pass one argument (`max`) that is used as the upper limit
+ * and the opposite (additive inverse or `-max`) as the lower limit.
+ *
+ * @param v - The value to clamp.
+ * @param max - The maximum value.
+ * @returns The clamped value.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * clampSym(5, 10) // returns 5
+ * clampSym(15, 10) // returns 10
+ * clampSym(-5, 10) // returns -5
+ * clampSym(-15, 10) // returns -10
+ * ```
+ **/
 export declare function clampSym(v: number, max: number): number;
 /**
-It returns the comparison value (an integer number) between two `float` values.
-**/
-export declare function compare(a: number, b: number): number;
+ * It returns the comparison value (an integer number) between two `float` values.
+ *
+ * @param a - The first value to compare.
+ * @param b - The second value to compare.
+ * @returns A number indicating the relative order of the two values.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * compare(5, 10) // returns -1
+ * compare(10, 5) // returns 1
+ * compare(5, 5) // returns 0
+ * ```
+ **/
+export declare function compareNumbers(a: number, b: number): number;
 /**
-Rounds a number down to the specified number of decimals.
-**/
+ * Rounds a number down to the specified number of decimals.
+ *
+ * @param v - The number to round down.
+ * @param decimals - The number of decimals to round down to.
+ * @returns The rounded down number.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * floorTo(1.234, 2) // returns 1.23
+ * floorTo(1.234, 1) // returns 1.2
+ * floorTo(1.234, 0) // returns 1
+ * ```
+ **/
 export declare function floorTo(v: number, decimals: number): number;
+/**
+ * Converts a number to its hexadecimal representation.
+ *
+ * @param num - The number to convert.
+ * @param length - The desired length of the hexadecimal string. Defaults to 0.
+ * @returns The hexadecimal representation of the number.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * toHex(255) // returns 'ff'
+ * toHex(255, 4) // returns '00ff'
+ * toHex(255, 8) // returns '000000ff'
+ * ```
+ */
 export declare function toHex(num: number, length?: number): string;
 /**
-`interpolate` returns a value between `a` and `b` for any value of `t` (normally between 0 and 1).
-**/
+ * `interpolate` returns a value between `a` and `b` for any value of `t` (normally between 0 and 1).
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param t - The interpolation value.
+ * @returns The interpolated value.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * interpolate(0, 10, 0.5) // returns 5
+ * interpolate(0, 10, 0.25) // returns 2.5
+ * interpolate(0, 10, 0.75) // returns 7.5
+ * ```
+ **/
 export declare function interpolate(a: number, b: number, t: number): number;
 /**
-Interpolates values in a polar coordinate system looking for the narrowest delta angle.
-It can be either clock-wise or counter-clock-wise.
-**/
+ * Interpolates values in a polar coordinate system looking for the narrowest delta angle.
+ * It can be either clock-wise or counter-clock-wise.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param t - The interpolation value.
+ * @param turn - The total number of degrees in a full turn. Default is 360.0.
+ * @returns The interpolated angle.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * interpolateAngle(0, 90, 0.5) // returns 45
+ * interpolateAngle(0, 270, 0.5) // returns 315
+ * interpolateAngle(0, 90, 0.25) // returns 22.5
+ * interpolateAngle(0, 270, 0.25) // returns 337.5
+ * ```
+ **/
 export declare function interpolateAngle(a: number, b: number, t: number, turn?: number): number;
+/**
+ * Calculates the widest angle difference between two angles.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param turn - The total angle of a full turn. Defaults to 360 degrees.
+ * @returns The widest angle difference between `a` and `b`.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * widestAngleDifference(0, 90) // returns 90
+ * widestAngleDifference(90, 0) // returns -90
+ * widestAngleDifference(0, 270) // returns -90
+ * widestAngleDifference(270, 0) // returns 90
+ * ```
+ */
 export declare function widestAngleDifference(a: number, b: number, turn?: number): number;
 /**
-Interpolates values in a polar coordinate system looking for the wideset delta angle.
-It can be either clock-wise or counter-clock-wise.
-**/
+ * Interpolates values in a polar coordinate system looking for the wideset delta angle.
+ * It can be either clock-wise or counter-clock-wise.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param t - The interpolation value.
+ * @param turn - The total number of degrees in a full turn. Default is 360.0.
+ * @returns The interpolated angle.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * interpolateWidestAngle(0, 90, 0.5) // returns 45
+ * interpolateWidestAngle(0, 270, 0.5) // returns 315
+ * interpolateWidestAngle(0, 90, 0.25) // returns 22.5
+ * interpolateWidestAngle(0, 270, 0.25) // returns 337.5
+ * ```
+ **/
 export declare function interpolateWidestAngle(a: number, b: number, t: number, turn?: number): number;
 /**
-Interpolates values in a polar coordinate system always in clock-wise direction.
-**/
+ * Interpolates values in a polar coordinate system always in clock-wise direction.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param t - The interpolation value.
+ * @param turn - The total number of degrees in a full turn. Default is 360.0.
+ * @returns The interpolated angle.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * interpolateAngleCW(0, 90, 0.5) // returns 45
+ * interpolateAngleCW(0, 270, 0.5) // returns 315
+ * interpolateAngleCW(0, 90, 0.25) // returns 22.5
+ * interpolateAngleCW(0, 270, 0.25) // returns 337.5
+ * ```
+ **/
 export declare function interpolateAngleCW(a: number, b: number, t: number, turn?: number): number;
 /**
-Interpolates values in a polar coordinate system always in counter-clock-wise direction.
-**/
+ * Interpolates values in a polar coordinate system always in counter-clock-wise direction.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param t - The interpolation value.
+ * @param turn - The total number of degrees in a full turn. Default is 360.0.
+ * @returns The interpolated angle.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * interpolateAngleCCW(0, 90, 0.5) // returns 45
+ * interpolateAngleCCW(0, 270, 0.5) // returns 315
+ * interpolateAngleCCW(0, 90, 0.25) // returns 22.5
+ * interpolateAngleCCW(0, 270, 0.25) // returns 337.5
+ * ```
+ **/
 export declare function interpolateAngleCCW(a: number, b: number, t: number, turn?: number): number;
 /**
-number numbers can sometime introduce tiny errors even for simple operations.
-`nearEquals` compares two floats using a tiny tollerance (last optional
-argument). By default it is defined as `EPSILON`.
-**/
+ * number numbers can sometime introduce tiny errors even for simple operations.
+ * `nearEquals` compares two floats using a tiny tollerance (last optional
+ * argument). By default it is defined as `EPSILON`.
+ *
+ * @param a - The first number to compare.
+ * @param b - The second number to compare.
+ * @param tollerance - The tollerance value. Default is `EPSILON`.
+ * @returns `true` if the numbers are very close, `false` otherwise.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * nearEquals(5, 5.000000000000001) // returns true
+ * nearEquals(5, 5.000000000001) // returns false
+ * nearEquals(5, 5.000000000001, 1e-9) // returns true
+ * ```
+ **/
 export declare function nearEquals(a: number, b: number, tollerance?: number): boolean;
 /**
-number numbers can sometime introduce tiny errors even for simple operations.
-`nearEqualAngles` compares two angles (default is 360deg) using a tiny
-tollerance (last optional argument). By default the tollerance is defined as
-`EPSILON`.
-**/
+ * number numbers can sometime introduce tiny errors even for simple operations.
+ * `nearEqualAngles` compares two angles (default is 360deg) using a tiny
+ * tollerance (last optional argument). By default the tollerance is defined as
+ * `EPSILON`.
+ *
+ * @param a - The first angle in degrees.
+ * @param b - The second angle in degrees.
+ * @param turn - The total number of degrees in a full turn. Default is 360.0.
+ * @param tollerance - The tollerance value. Default is `EPSILON`.
+ * @returns `true` if the angles are very close, `false` otherwise.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * nearEqualAngles(0, 360) // returns true
+ * nearEqualAngles(0, 361) // returns false
+ * nearEqualAngles(0, 360.000000000001) // returns true
+ * nearEqualAngles(0, 361, 360, 1) // returns true
+ * ```
+ **/
 export declare function nearEqualAngles(a: number, b: number, turn?: number, tollerance?: number): boolean;
 /**
-`nearZero` finds if the passed number is zero or very close to it. By default
-`EPSILON` is used as the tollerance value.
-**/
+ * `nearZero` finds if the passed number is zero or very close to it. By default
+ * `EPSILON` is used as the tollerance value.
+ *
+ * @param n - The number to check.
+ * @param tollerance - The tollerance value. Default is `EPSILON`.
+ * @returns `true` if the number is zero or very close to it, `false` otherwise.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * nearZero(0.000000000000001) // returns true
+ * nearZero(0.000000001) // returns false
+ * nearZero(0.000000001, 1e-9) // returns true
+ * ```
+ **/
 export declare function nearZero(n: number, tollerance?: number): boolean;
 /**
-Computes the nth root (`index`) of `base`.
-**/
+ * Computes the nth root (`index`) of `base`.
+ *
+ * @param base - The base number.
+ * @param index - The index of the root.
+ * @returns The nth root of the base number.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * root(8, 3) // returns 2
+ * root(27, 3) // returns 3
+ * root(16, 4) // returns 2
+ * ```
+ **/
 export declare function root(base: number, index: number): number;
 /**
-Rounds a number to the specified number of decimals.
-**/
+ * Rounds a number to the specified number of decimals.
+ *
+ * @param f - The number to round.
+ * @param decimals - The number of decimals to round to.
+ * @returns The rounded number.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * roundTo(1.234, 2) // returns 1.23
+ * roundTo(1.234, 1) // returns 1.2
+ * roundTo(1.234, 0) // returns 1
+ * ```
+ **/
 export declare function roundTo(f: number, decimals: number): number;
 /**
-`sign` returns `-1` if `value` is a negative number, `1` otherwise.
-*/
+ * `sign` returns `-1` if `value` is a negative number, `1` otherwise.
+ *
+ * @param value - The number to check.
+ * @returns `-1` if the number is negative, `1` otherwise.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * sign(-5) // returns -1
+ * sign(5) // returns 1
+ * ```
+ */
 export declare function sign<T extends number>(value: T): number;
 /**
-Passed two boundaries values (`min`, `max`), `wrap` ensures that the passed value `v` will
-be included in the boundaries. If the value exceeds `max`, the value is reduced by `min`
-repeatedely until it falls within the range. Similar and inverted treatment is performed if
-the value is below `min`.
-**/
+ * Passed two boundaries values (`min`, `max`), `wrap` ensures that the passed value `v` will
+ * be included in the boundaries. If the value exceeds `max`, the value is reduced by `min`
+ * repeatedely until it falls within the range. Similar and inverted treatment is performed if
+ * the value is below `min`.
+ *
+ * @param v - The value to wrap.
+ * @param min - The minimum value of the range.
+ * @param max - The maximum value of the range.
+ * @returns The wrapped value.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * wrap(5, 0, 10) // returns 5
+ * wrap(15, 0, 10) // returns 5
+ * wrap(-5, 0, 10) // returns 5
+ * ```
+ **/
 export declare function wrap(v: number, min: number, max: number): number;
 /**
-Similar to `wrap`, it works for numbers between 0 and `max`.
-**/
+ * Similar to `wrap`, it works for numbers between 0 and `max`.
+ *
+ * @param v - The value to wrap.
+ * @param max - The maximum value of the range.
+ * @returns The wrapped value.
+ * @public
+ * @remarks
+ * @example
+ * ```ts
+ * wrapCircular(5, 10) // returns 5
+ * wrapCircular(15, 10) // returns 5
+ * wrapCircular(-5, 10) // returns 5
+ * ```
+ **/
 export declare function wrapCircular(v: number, max: number): number;

package/number.js

@@ -1,55 +1,55 @@
 import { lpad as l } from "./string.js";
-const p = 1e-4, f = 1e-9;
+const f = 1e-9;
 function u(n, t, e = 360) {
   let r = (t - n) % e;
   return r < 0 && (r += e), r > e / 2 && (r -= e), r;
 }
-function h(n, t) {
+function p(n, t) {
   const e = Math.pow(10, t);
   return Math.ceil(n * e) / e;
 }
 function c(n, t, e) {
   return Math.min(Math.max(n, t), e);
 }
-function M(n, t, e) {
+function h(n, t, e) {
   return Math.trunc(c(n, t, e));
 }
-function g(n, t) {
+function M(n, t) {
   return c(n, -t, t);
 }
-function N(n, t) {
+function g(n, t) {
   return n < t ? -1 : n > t ? 1 : 0;
 }
-function w(n, t) {
+function N(n, t) {
   const e = Math.pow(10, t);
   return Math.floor(n * e) / e;
 }
-function A(n, t = 0) {
+function w(n, t = 0) {
   return l(n.toString(16), "0", t);
 }
 function o(n, t, e) {
   return (t - n) * e + n;
 }
-function d(n, t, e, r = 360) {
+function A(n, t, e, r = 360) {
   return i(o(n, n + u(n, t, r), e), r);
 }
 function a(n, t, e = 360) {
   let r = (t - n) % e;
   return r < 0 && (r += e), r > e / 2 && (r -= e), r;
 }
-function C(n, t, e, r = 360) {
+function d(n, t, e, r = 360) {
   return i(
     o(n, n + a(n, t, r), e),
     r
   );
 }
-function E(n, t, e, r = 360) {
+function m(n, t, e, r = 360) {
   return n = i(n, r), t = i(t, r), t < n && (t += r), i(o(n, t, e), r);
 }
-function T(n, t, e, r = 360) {
+function C(n, t, e, r = 360) {
   return n = i(n, r), t = i(t, r), t > n && (t -= r), i(o(n, t, e), r);
 }
-function m(n, t, e = f) {
+function E(n, t, e = f) {
   return isFinite(n) ? isFinite(t) ? Math.abs(n - t) <= e : !1 : isNaN(n) ? isNaN(t) : isNaN(t) || isFinite(t) ? !1 : n > 0 == t > 0;
 }
 function F(n, t, e = 360, r = f) {
@@ -58,17 +58,17 @@ function F(n, t, e = 360, r = f) {
 function S(n, t = f) {
   return Math.abs(n) <= t;
 }
-function W(n, t) {
+function T(n, t) {
   return Math.pow(n, 1 / t);
 }
-function q(n, t) {
+function W(n, t) {
   const e = Math.pow(10, t);
   return Math.round(n * e) / e;
 }
-function D(n) {
+function q(n) {
   return n < 0 ? -1 : 1;
 }
-function I(n, t, e) {
+function D(n, t, e) {
   const r = e - t + 1;
   return n < t && (n += r * ((t - n) / r + 1)), t + (n - t) % r;
 }
@@ -77,27 +77,26 @@ function i(n, t) {
 }
 export {
   f as EPSILON,
-  p as TOLERANCE,
   u as angleDifference,
-  h as ceilTo,
+  p as ceilTo,
   c as clamp,
-  M as clampInt,
-  g as clampSym,
-  N as compare,
-  w as floorTo,
+  h as clampInt,
+  M as clampSym,
+  g as compareNumbers,
+  N as floorTo,
   o as interpolate,
-  d as interpolateAngle,
-  T as interpolateAngleCCW,
-  E as interpolateAngleCW,
-  C as interpolateWidestAngle,
+  A as interpolateAngle,
+  C as interpolateAngleCCW,
+  m as interpolateAngleCW,
+  d as interpolateWidestAngle,
   F as nearEqualAngles,
-  m as nearEquals,
+  E as nearEquals,
   S as nearZero,
-  W as root,
-  q as roundTo,
-  D as sign,
-  A as toHex,
+  T as root,
+  W as roundTo,
+  q as sign,
+  w as toHex,
   a as widestAngleDifference,
-  I as wrap,
+  D as wrap,
   i as wrapCircular
 };

package/object.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function s(e){return Object.keys(e)}function c(e,t){const u=s(e),r=s(t);if(u.length!==r.length)return!1;for(const n of u)if(!(n in t))return!1;return!0}function i(e){return e!=null&&Object.getPrototypeOf(e)===Object.prototype}function o(e,...t){return s(e).reduce((r,n)=>(t.includes(n)||(r[n]=e[n]),r),{})}function f(e,t){return Object.assign({},e,t)}function l(e){return e==null||i(e)&&Object.keys(e).length===0}exports.isEmpty=l;exports.isObject=i;exports.keys=s;exports.merge=f;exports.removeFields=o;exports.sameKeys=c;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function c(e){return Object.keys(e)}function o(e,t){const s=c(e),r=c(t);if(s.length!==r.length)return!1;for(const n of s)if(!(n in t))return!1;return!0}function u(e){return e!=null&&Object.getPrototypeOf(e)===Object.prototype}function i(e,...t){return c(e).reduce((r,n)=>(t.includes(n)||(r[n]=e[n]),r),{})}function b(e,t){return Object.assign({},e,t)}function j(e){return Object.keys(e).length===0}exports.isEmptyObject=j;exports.isObject=u;exports.mergeObjects=b;exports.objectKeys=c;exports.removeObjectFields=i;exports.sameObjectKeys=o;

package/object.d.ts

@@ -1,8 +1,56 @@
 import { IndexKey, Merge, TupleToUnion } from './domain';
 
-export declare function keys<T extends object>(obj: T): Array<keyof T>;
-export declare function sameKeys<T extends object>(a: T, b: T): boolean;
+/**
+ * Returns an array of keys from the given object.
+ *
+ * @param obj - The object from which to extract keys.
+ * @returns An array of keys from the object.
+ * @public
+ */
+export declare function objectKeys<T extends object>(obj: T): Array<keyof T>;
+/**
+ * Checks if two objects have the same keys.
+ *
+ * @param a - The first object.
+ * @param b - The second object.
+ * @returns `true` if both objects have the same keys, `false` otherwise.
+ * @public
+ */
+export declare function sameObjectKeys<T extends object>(a: T, b: T): boolean;
+/**
+ * Checks if the given value is an object.
+ *
+ * @param obj - The value to check.
+ * @returns `true` if the value is an object, `false` otherwise.
+ * @public
+ */
 export declare function isObject(obj: unknown): obj is Record<IndexKey, unknown>;
-export declare function removeFields<T extends object, F extends Array<keyof T>>(ob: T, ...fields: F): Omit<T, TupleToUnion<F>>;
-export declare function merge<A extends Record<IndexKey, unknown>, B extends Record<IndexKey, unknown>>(a: A, b: B): Merge<A, B>;
-export declare function isEmpty(obj: object): boolean;
+/**
+ * Removes specified fields from an object and returns a new object without those fields.
+ *
+ * @param ob - The object from which fields will be removed.
+ * @param fields - The fields to be removed from the object.
+ * @returns A new object without the specified fields.
+ * @public
+ */
+export declare function removeObjectFields<T extends object, F extends Array<keyof T>>(ob: T, ...fields: F): Omit<T, TupleToUnion<F>>;
+/**
+ * Merges two objects together.
+ *
+ * @typeParam A - The type of the first object.
+ * @typeParam B - The type of the second object.
+ * @param a - The first object to merge.
+ * @param b - The second object to merge.
+ * @returns The merged object.
+ * @public
+ */
+export declare function mergeObjects<A extends Record<IndexKey, unknown>, B extends Record<IndexKey, unknown>>(a: A, b: B): Merge<A, B>;
+/**
+ * Checks if an object is empty.
+ * An object is considered empty if it has no own enumerable properties.
+ *
+ * @param obj - The object to check.
+ * @returns `true` if the object is empty, `false` otherwise.
+ * @public
+ */
+export declare function isEmptyObject(obj: object): boolean;