Lady’s Gitweb - Pisces/blob - value.js

   1 // ♓🌟 Piscēs ∷ value.js
   2 // ====================================================================
   3 //
   4 // Copyright © 2022‐2023 Lady [@ Lady’s Computer].
   5 //
   6 // This Source Code Form is subject to the terms of the Mozilla Public
   7 // License, v. 2.0. If a copy of the MPL was not distributed with this
   8 // file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
   9
  10 export const {
  11   /** The welknown `@@asyncIterator` symbol. */
  12   asyncIterator: ASYNC_ITERATOR,
  13
  14   /** The welknown `@@hasInstance` symbol. */
  15   hasInstance: HAS_INSTANCE,
  16
  17   /** The welknown `@@isConcatSpreadable` symbol. */
  18   isConcatSpreadable: IS_CONCAT_SPREADABLE,
  19
  20   /** The welknown `@@iterator` symbol. */
  21   iterator: ITERATOR,
  22
  23   /** The welknown `@@match` symbol. */
  24   match: MATCH,
  25
  26   /** The welknown `@@matchAll` symbol. */
  27   matchAll: MATCH_ALL,
  28
  29   /** The welknown `@@replace` symbol. */
  30   replace: REPLACE,
  31
  32   /** The welknown `@@species` symbol. */
  33   species: SPECIES,
  34
  35   /** The welknown `@@split` symbol. */
  36   split: SPLIT,
  37
  38   /** The welknown `@@toPrimitive` symbol. */
  39   toPrimitive: TO_PRIMITIVE,
  40
  41   /** The welknown `@@toStringTag` symbol. */
  42   toStringTag: TO_STRING_TAG,
  43
  44   /** The welknown `@@unscopables` symbol. */
  45   unscopables: UNSCOPABLES,
  46 } = Symbol;
  47
  48 /** The null primitive. */
  49 export const NULL = null;
  50
  51 /** The undefined primitive. */
  52 export const UNDEFINED = undefined;
  53
  54 export const {
  55   /**
  56    * Returns the primitive value of the provided object per its
  57    * `.toString` and `.valueOf` methods.
  58    *
  59    * If the provided hint is "string", then `.toString` takes
  60    * precedence; otherwise, `.valueOf` does.
  61    *
  62    * Throws an error if both of these methods are not callable or do
  63    * not return a primitive.
  64    */
  65   ordinaryToPrimitive,
  66
  67   /**
  68    * Returns the provided value converted to a primitive, or throws if
  69    * no such conversion is possible.
  70    *
  71    * The provided preferred type, if specified, should be "string",
  72    * "number", or "default". If the provided input has a
  73    * `.[Symbol.toPrimitive]` method, this function will throw rather
  74    * than calling that method with a preferred type other than one of
  75    * the above.
  76    */
  77   toPrimitive,
  78 } = (() => {
  79   const { apply: call } = Reflect;
  80
  81   return {
  82     ordinaryToPrimitive: (O, hint) => {
  83       const methodNames = hint == "string"
  84         ? ["toString", "valueOf"]
  85         : ["valueOf", "toString"];
  86       for (let index = 0; index < methodNames.length; ++index) {
  87         const method = O[methodNames[index]];
  88         if (typeof method === "function") {
  89           // Method is callable.
  90           const result = call(method, O, []);
  91           if (type(result) !== "object") {
  92             // Method returns a primitive.
  93             return result;
  94           } else {
  95             // Method returns an object.
  96             continue;
  97           }
  98         } else {
  99           // Method is not callable.
 100           continue;
 101         }
 102       }
 103       throw new TypeError(
 104         "Piscēs: Unable to convert object to primitive",
 105       );
 106     },
 107     toPrimitive: ($, preferredType = "default") => {
 108       const hint = `${preferredType}`;
 109       if (
 110         "default" !== hint && "string" !== hint &&
 111         "number" !== hint
 112       ) {
 113         // An invalid preferred type was specified.
 114         throw new TypeError(
 115           `Piscēs: Invalid preferred type: ${preferredType}.`,
 116         );
 117       } else if (type($) === "object") {
 118         // The provided value is an object.
 119         const exoticToPrim = $[TO_PRIMITIVE] ?? undefined;
 120         if (exoticToPrim !== undefined) {
 121           // The provided value has an exotic primitive conversion
 122           // method.
 123           if (typeof exoticToPrim !== "function") {
 124             // The method is not callable.
 125             throw new TypeError(
 126               "Piscēs: `.[Symbol.toPrimitive]` was neither nullish nor callable.",
 127             );
 128           } else {
 129             // The method is callable.
 130             return call(exoticToPrim, $, [hint]);
 131           }
 132         } else {
 133           // Use the ordinary primitive conversion function.
 134           return ordinaryToPrimitive($, hint);
 135         }
 136       } else {
 137         // The provided value is already a primitive.
 138         return $;
 139       }
 140     },
 141   };
 142 })();
 143
 144 /**
 145  * Returns whether the provided values are the same value.
 146  *
 147  * ※ This differs from `===` in the cases of nan and zero.
 148  */
 149 export const sameValue = Object.is;
 150
 151 export const {
 152   /**
 153    * Returns whether the provided values are either the same value or
 154    * both zero (either positive or negative).
 155    *
 156    * ※ This differs from `===` in the case of nan.
 157    */
 158   sameValueZero,
 159 } = (() => {
 160   const { isNaN: isNan } = Number;
 161   return {
 162     sameValueZero: ($1, $2) => {
 163       const type1 = type($1);
 164       const type2 = type($2);
 165       if (type1 !== type2) {
 166         // The provided values are not of the same type.
 167         return false;
 168       } else if (type1 === "number") {
 169         // The provided values are numbers; check if they are nan and
 170         // use strict equality otherwise.
 171         return isNan($1) && isNan($2) || $1 === $2;
 172       } else {
 173         // The provided values are not numbers; use strict equality.
 174         return $1 === $2;
 175       }
 176     },
 177   };
 178 })();
 179
 180 /**
 181  * Returns a lowercase string identifying the type of the provided
 182  * value.
 183  *
 184  * This differs from the value of the `typeof` operator only in the
 185  * cases of objects and null.
 186  */
 187 export const type = ($) => {
 188   if ($ === null) {
 189     // The provided value is null.
 190     return "null";
 191   } else {
 192     // The provided value is not null.
 193     const type·of = typeof $;
 194     return type·of === "function" ? "object" : type·of;
 195   }
 196 };