Add methods for own entries and values to object.js

[Pisces] / value.js

diff --git a/value.js b/value.js
index 77cb6b40448f5ca4ae7d08cf001625242c1e09a3..cf858ad2a32bfc1b5e7445aebc67e4ee8a0f1577 100644 (file)
--- a/value.js
+++ b/value.js
@@ -1,46 +1,301 @@
 // ♓🌟 Piscēs ∷ value.js
 // ====================================================================
 //
 // ♓🌟 Piscēs ∷ value.js
 // ====================================================================
 //

-// Copyright © 2022 Lady [@ Lady’s Computer].
+// Copyright © 2022‐2023 Lady [@ Lady’s Computer].

 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
 
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
 

-import { call } from "./function.js";
+export const {
+  /** The welknown `@@asyncIterator` symbol. */
+  asyncIterator: ASYNC_ITERATOR,
+
+  /** The welknown `@@hasInstance` symbol. */
+  hasInstance: HAS_INSTANCE,
+
+  /** The welknown `@@isConcatSpreadable` symbol. */
+  isConcatSpreadable: IS_CONCAT_SPREADABLE,
+
+  /** The welknown `@@iterator` symbol. */
+  iterator: ITERATOR,
+
+  /** The welknown `@@match` symbol. */
+  match: MATCH,
+
+  /** The welknown `@@matchAll` symbol. */
+  matchAll: MATCH_ALL,
+
+  /** The welknown `@@replace` symbol. */
+  replace: REPLACE,
+
+  /** The welknown `@@species` symbol. */
+  species: SPECIES,
+
+  /** The welknown `@@split` symbol. */
+  split: SPLIT,
+
+  /** The welknown `@@toPrimitive` symbol. */
+  toPrimitive: TO_PRIMITIVE,
+
+  /** The welknown `@@toStringTag` symbol. */
+  toStringTag: TO_STRING_TAG,
+
+  /** The welknown `@@unscopables` symbol. */
+  unscopables: UNSCOPABLES,
+} = Symbol;
+
+export const {
+  /**
+   * ln(10).
+   *
+   * ※ This is an alias for `Math.LN10`.
+   */
+  LN10,
+
+  /**
+   * ln(2).
+   *
+   * ※ This is an alias for `Math.LN2`.
+   */
+  LN2,
+
+  /**
+   * log10(ℇ).
+   *
+   * ※ This is an alias for `Math.LOG10E`.
+   */
+  LOG10E: LOG10ℇ,
+
+  /**
+   * log2(ℇ).
+   *
+   * ※ This is an alias for `Math.LOG2E`.
+   */
+  LOG2E: LOG2ℇ,
+
+  /**
+   * sqrt(½).
+   *
+   * ※ This is an alias for `Math.SQRT1_2`.
+   */
+  SQRT1_2: RECIPROCAL_SQRT2,
+
+  /**
+   * sqrt(2).
+   *
+   * ※ This is an alias for `Math.SQRT2`.
+   */
+  SQRT2,
+
+  /**
+   * The mathematical constant π.
+   *
+   * ※ This is an alias for `Math.PI`.
+   */
+  PI: Π,
+
+  /**
+   * The Euler number.
+   *
+   * ※ This is an alias for `Math.E`.
+   */
+  E: ℇ,
+} = Math;
+
+export const {
+  /**
+   * The largest number value less than infinity.
+   *
+   * ※ This is an alias for `Number.MAX_VALUE`.
+   */
+  MAX_VALUE: MAXIMUM_NUMBER,
+
+  /**
+   * 2**53 - 1.
+   *
+   * ※ This is an alias for `Number.MAX_SAFE_INTEGER`.
+   */
+  MAX_SAFE_INTEGER: MAXIMUM_SAFE_INTEGRAL_NUMBER,
+
+  /**
+   * The smallest number value greater than negative infinity.
+   *
+   * ※ This is an alias for `Number.MIN_VALUE`.
+   */
+  MIN_VALUE: MINIMUM_NUMBER,
+
+  /**
+   * -(2**53 - 1).
+   *
+   * ※ This is an alias for `Number.MIN_SAFE_INTEGER`.
+   */
+  MIN_SAFE_INTEGER: MINIMUM_SAFE_INTEGRAL_NUMBER,
+
+  /**
+   * Negative infinity.
+   *
+   * ※ This is an alias for `Number.NEGATIVE_INFINITY`.
+   */
+  NEGATIVE_INFINITY,
+
+  /**
+   * Nan.
+   *
+   * ※ This is an alias for `Number.NaN`.
+   */
+  NaN: NAN,
+
+  /**
+   * Positive infinity.
+   *
+   * ※ This is an alias for `Number.POSITIVE_INFINITY`.
+   */
+  POSITIVE_INFINITY,
+
+  /**
+   * The difference between 1 and the smallest number greater than 1.
+   *
+   * ※ This is an alias for `Number.EPSILON`.
+   */
+  EPSILON: Ε,
+} = Number;
+
+/** Negative zero. */
+export const NEGATIVE_ZERO = -0;

 
 /** The null primitive. */
 export const NULL = null;
 
 
 /** The null primitive. */
 export const NULL = null;
 

+/** Positive zero. */
+export const POSITIVE_ZERO = 0;
+

 /** The undefined primitive. */
 export const UNDEFINED = undefined;
 
 /** The undefined primitive. */
 export const UNDEFINED = undefined;
 

+/**
+ * Completes the provided property descriptor by setting missing values
+ * to their defaults.
+ *
+ * ※ This method modifies the provided object and returns undefined.
+ */
+export const completePropertyDescriptor = (Desc) => {
+  if (Desc === UNDEFINED) {
+    throw new TypeError(
+      "Piscēs: Cannot complete undefined property descriptor.",
+    );
+  } else if (!("get" in Desc || "set" in Desc)) {
+    // This is a generic or data descriptor.
+    if (!("value" in Desc)) {
+      // `value` is not defined on this.
+      Desc.value = UNDEFINED;
+    } else {
+      // `value` is already defined on this.
+      /* do nothing */
+    }
+    if (!("writable" in Desc)) {
+      // `writable` is not defined on this.
+      Desc.writable = false;
+    } else {
+      // `writable` is already defined on this.
+      /* do nothing */
+    }
+  } else {
+    // This is not a generic or data descriptor.
+    if (!("get" in Desc)) {
+      // `get` is not defined on this.
+      Desc.get = UNDEFINED;
+    } else {
+      // `get` is already defined on this.
+      /* do nothing */
+    }
+    if (!("set" in Desc)) {
+      // `set` is not defined on this.
+      Desc.set = UNDEFINED;
+    } else {
+      // `set` is already defined on this.
+      /* do nothing */
+    }
+  }
+  if (!("enumerable" in Desc)) {
+    // `enumerable` is not defined on this.
+    Desc.enumerable = false;
+  } else {
+    // `enumerable` is already defined on this.
+    /* do nothing */
+  }
+  if (!("configurable" in Desc)) {
+    // `configurable` is not defined on this.
+    Desc.configurable = false;
+  } else {
+    // `configurable` is already defined on this.
+    /* do nothing */
+  }
+};
+
+/** Gets whether the provided value is an accessor descrtiptor. */
+export const isAccessorDescriptor = (Desc) =>
+  Desc !== UNDEFINED && ("get" in Desc || "set" in Desc);
+
+/** Gets whether the provided value is a data descrtiptor. */
+export const isDataDescriptor = (Desc) =>
+  Desc !== UNDEFINED && ("value" in Desc || "writable" in Desc);
+
+/**
+ * Gets whether the provided value is a fully‐populated property
+ * descriptor.
+ */
+export const isFullyPopulatedDescriptor = (Desc) =>
+  Desc !== UNDEFINED &&
+  ("value" in Desc && "writable" in Desc ||
+    "get" in Desc && "set" in Desc) &&
+  "enumerable" in Desc && "configurable" in Desc;
+
+/**
+ * Gets whether the provided value is a generic (not accessor or data)
+ * descrtiptor.
+ */
+export const isGenericDescriptor = (Desc) =>
+  Desc !== UNDEFINED &&
+  !("get" in Desc || "set" in Desc || "value" in Desc ||
+    "writable" in Desc);
+

 export const {
   /**
    * Returns the primitive value of the provided object per its
 export const {
   /**
    * Returns the primitive value of the provided object per its

-   * `toString` and `valueOf` methods.
+   * `.toString` and `.valueOf` methods.

    *
    *

-   * If the provided hint is "string", then `toString` takes
-   * precedence; otherwise, `valueOf` does.
+   * If the provided hint is "string", then `.toString` takes
+   * precedence; otherwise, `.valueOf` does.

    *
    * Throws an error if both of these methods are not callable or do
    * not return a primitive.
    */
   ordinaryToPrimitive,
 
    *
    * Throws an error if both of these methods are not callable or do
    * not return a primitive.
    */
   ordinaryToPrimitive,
 

+  /**
+   * Returns a string function name generated from the provided value
+   * and optional prefix.
+   */
+  toFunctionName,
+

   /**
    * Returns the provided value converted to a primitive, or throws if
    * no such conversion is possible.
    *
    * The provided preferred type, if specified, should be "string",
    * "number", or "default". If the provided input has a
   /**
    * Returns the provided value converted to a primitive, or throws if
    * no such conversion is possible.
    *
    * The provided preferred type, if specified, should be "string",
    * "number", or "default". If the provided input has a

-   * `[Symbol.toPrimitive]` method, this function will throw rather
+   * `.[Symbol.toPrimitive]` method, this function will throw rather

    * than calling that method with a preferred type other than one of
    * the above.
    */
   toPrimitive,
 } = (() => {
    * than calling that method with a preferred type other than one of
    * the above.
    */
   toPrimitive,
 } = (() => {

-  const { toPrimitive: toPrimitiveSymbol } = Symbol;
+  const { apply: call } = Reflect;
+  const getSymbolDescription = Object.getOwnPropertyDescriptor(
+    Symbol.prototype,
+    "description",
+  ).get;

 
   return {
     ordinaryToPrimitive: (O, hint) => {
 
   return {
     ordinaryToPrimitive: (O, hint) => {


@@ -68,6 +323,21 @@ export const {
         "Piscēs: Unable to convert object to primitive",
       );
     },
         "Piscēs: Unable to convert object to primitive",
       );
     },

+    toFunctionName: ($, prefix = UNDEFINED) => {
+      const key = toPrimitive($, "string");
+      const name = (() => {
+        if (typeof key === "symbol") {
+          // The provided value is a symbol; format its description.
+          const description = call(getSymbolDescription, key, []);
+          return description === UNDEFINED ? "" : `[${description}]`;
+        } else {
+          // The provided value not a symbol; convert it to a string
+          // property key.
+          return `${key}`;
+        }
+      })();
+      return prefix !== UNDEFINED ? `${prefix} ${name}` : name;
+    },

     toPrimitive: ($, preferredType = "default") => {
       const hint = `${preferredType}`;
       if (
     toPrimitive: ($, preferredType = "default") => {
       const hint = `${preferredType}`;
       if (


@@ -80,14 +350,14 @@ export const {
         );
       } else if (type($) === "object") {
         // The provided value is an object.
         );
       } else if (type($) === "object") {
         // The provided value is an object.

-        const exoticToPrim = $[toPrimitiveSymbol] ?? undefined;
-        if (exoticToPrim !== undefined) {
+        const exoticToPrim = $[TO_PRIMITIVE] ?? UNDEFINED;
+        if (exoticToPrim !== UNDEFINED) {

           // The provided value has an exotic primitive conversion
           // method.
           if (typeof exoticToPrim !== "function") {
             // The method is not callable.
             throw new TypeError(
           // The provided value has an exotic primitive conversion
           // method.
           if (typeof exoticToPrim !== "function") {
             // The method is not callable.
             throw new TypeError(

-              "Piscēs: `[Symbol.toPrimitive]` was neither nullish nor callable.",
+              "Piscēs: `.[Symbol.toPrimitive]` was neither nullish nor callable.",

             );
           } else {
             // The method is callable.
             );
           } else {
             // The method is callable.


@@ -105,14 +375,14 @@ export const {
   };
 })();
 
   };
 })();
 

-/**
- * Returns whether the provided values are the same value.
- *
- * ※ This differs from `===` in the cases of nan and zero.
- */
-export const sameValue = Object.is;
-

 export const {
 export const {

+  /**
+   * Returns whether the provided values are the same value.
+   *
+   * ※ This differs from `===` in the cases of nan and zero.
+   */
+  sameValue,
+

   /**
    * Returns whether the provided values are either the same value or
    * both zero (either positive or negative).
   /**
    * Returns whether the provided values are either the same value or
    * both zero (either positive or negative).


@@ -120,9 +390,23 @@ export const {
    * ※ This differs from `===` in the case of nan.
    */
   sameValueZero,
    * ※ This differs from `===` in the case of nan.
    */
   sameValueZero,

+
+  /**
+   * Returns the result of converting the provided value to an index,
+   * or throws an error if it is out of range.
+   */
+  toIndex,
+
+  /**
+   * Returns the result of converting the provided value to a length.
+   */
+  toLength,

 } = (() => {
 } = (() => {

+  const { floor, max, min } = Math;

   const { isNaN: isNan } = Number;
   const { isNaN: isNan } = Number;

+  const { is } = Object;

   return {
   return {

+    sameValue: (a, b) => is(a, b),

     sameValueZero: ($1, $2) => {
       const type1 = type($1);
       const type2 = type($2);
     sameValueZero: ($1, $2) => {
       const type1 = type($1);
       const type2 = type($2);


@@ -138,9 +422,41 @@ export const {
         return $1 === $2;
       }
     },
         return $1 === $2;
       }
     },

+    toIndex: ($) => {
+      const integer = floor($);
+      if (isNan(integer) || integer == 0) {
+        // The value is zero·like.
+        return 0;
+      } else {
+        // The value is not zero·like.
+        const clamped = toLength(integer);
+        if (clamped !== integer) {
+          // Clamping the value changes it.
+          throw new RangeError(`Piscēs: Index out of range: ${$}.`);
+        } else {
+          // The value is within appropriate bounds.
+          return integer;
+        }
+      }
+    },
+    toLength: ($) => {
+      const len = floor($);
+      return isNan(len) || len == 0
+        ? 0
+        : max(min(len, MAXIMUM_SAFE_INTEGRAL_NUMBER), 0);
+    },

   };
 })();
 
   };
 })();
 

+/**
+ * Returns the property key (symbol or string) corresponding to the
+ * provided value.
+ */
+export const toPropertyKey = ($) => {
+  const key = toPrimitive($, "string");
+  return typeof key === "symbol" ? key : `${key}`;
+};
+

 /**
  * Returns a lowercase string identifying the type of the provided
  * value.
 /**
  * Returns a lowercase string identifying the type of the provided
  * value.