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 /**
  55  * Returns −0 if the provided argument is "-0"; returns a number
  56  * representing the index if the provided argument is a canonical
  57  * numeric index string; otherwise, returns undefined.
  58  *
  59  * There is no clamping of the numeric index, but note that numbers
  60  * above 2^53 − 1 are not safe nor valid integer indices.
  61  */
  62 export const canonicalNumericIndexString = ($) => {
  63   if (typeof $ !== "string") {
  64     return undefined;
  65   } else if ($ === "-0") {
  66     return -0;
  67   } else {
  68     const n = +$;
  69     return $ === `${n}` ? n : undefined;
  70   }
  71 };
  72
  73 /**
  74  * Returns the length of the provided arraylike value.
  75  *
  76  * This can produce larger lengths than can actually be stored in
  77  * arrays, because no such restrictions exist on arraylike methods.
  78  *
  79  * ☡ This function throws if the provided value is not arraylike.
  80  */
  81 export const lengthOfArraylike = ({ length }) => toLength(length);
  82
  83 export const {
  84   /**
  85    * Returns the primitive value of the provided object per its
  86    * `.toString` and `.valueOf` methods.
  87    *
  88    * If the provided hint is "string", then `.toString` takes
  89    * precedence; otherwise, `.valueOf` does.
  90    *
  91    * Throws an error if both of these methods are not callable or do
  92    * not return a primitive.
  93    */
  94   ordinaryToPrimitive,
  95
  96   /**
  97    * Returns the provided value converted to a primitive, or throws if
  98    * no such conversion is possible.
  99    *
 100    * The provided preferred type, if specified, should be "string",
 101    * "number", or "default". If the provided input has a
 102    * `.[Symbol.toPrimitive]` method, this function will throw rather
 103    * than calling that method with a preferred type other than one of
 104    * the above.
 105    */
 106   toPrimitive,
 107 } = (() => {
 108   const { apply: call } = Reflect;
 109
 110   return {
 111     ordinaryToPrimitive: (O, hint) => {
 112       const methodNames = hint == "string"
 113         ? ["toString", "valueOf"]
 114         : ["valueOf", "toString"];
 115       for (let index = 0; index < methodNames.length; ++index) {
 116         const method = O[methodNames[index]];
 117         if (typeof method === "function") {
 118           // Method is callable.
 119           const result = call(method, O, []);
 120           if (type(result) !== "object") {
 121             // Method returns a primitive.
 122             return result;
 123           } else {
 124             // Method returns an object.
 125             continue;
 126           }
 127         } else {
 128           // Method is not callable.
 129           continue;
 130         }
 131       }
 132       throw new TypeError(
 133         "Piscēs: Unable to convert object to primitive",
 134       );
 135     },
 136     toPrimitive: ($, preferredType = "default") => {
 137       const hint = `${preferredType}`;
 138       if (
 139         "default" !== hint && "string" !== hint &&
 140         "number" !== hint
 141       ) {
 142         // An invalid preferred type was specified.
 143         throw new TypeError(
 144           `Piscēs: Invalid preferred type: ${preferredType}.`,
 145         );
 146       } else if (type($) === "object") {
 147         // The provided value is an object.
 148         const exoticToPrim = $[TO_PRIMITIVE] ?? undefined;
 149         if (exoticToPrim !== undefined) {
 150           // The provided value has an exotic primitive conversion
 151           // method.
 152           if (typeof exoticToPrim !== "function") {
 153             // The method is not callable.
 154             throw new TypeError(
 155               "Piscēs: `.[Symbol.toPrimitive]` was neither nullish nor callable.",
 156             );
 157           } else {
 158             // The method is callable.
 159             return call(exoticToPrim, $, [hint]);
 160           }
 161         } else {
 162           // Use the ordinary primitive conversion function.
 163           return ordinaryToPrimitive($, hint);
 164         }
 165       } else {
 166         // The provided value is already a primitive.
 167         return $;
 168       }
 169     },
 170   };
 171 })();
 172
 173 export const {
 174   /**
 175    * Returns whether the provided values are the same value.
 176    *
 177    * ※ This differs from `===` in the cases of nan and zero.
 178    */
 179   sameValue,
 180
 181   /**
 182    * Returns whether the provided values are either the same value or
 183    * both zero (either positive or negative).
 184    *
 185    * ※ This differs from `===` in the case of nan.
 186    */
 187   sameValueZero,
 188
 189   /**
 190    * Returns the result of converting the provided value to an index,
 191    * or throws an error if it is out of range.
 192    */
 193   toIndex,
 194
 195   /**
 196    * Returns the result of converting the provided value to a length.
 197    */
 198   toLength,
 199 } = (() => {
 200   const { floor, max, min } = Math;
 201   const {
 202     MAX_SAFE_INTEGER: MAXIMUM_SAFE_INTEGRAL_NUMBER,
 203     isNaN: isNan,
 204   } = Number;
 205   const { is } = Object;
 206   return {
 207     sameValue: (a, b) => is(a, b),
 208     sameValueZero: ($1, $2) => {
 209       const type1 = type($1);
 210       const type2 = type($2);
 211       if (type1 !== type2) {
 212         // The provided values are not of the same type.
 213         return false;
 214       } else if (type1 === "number") {
 215         // The provided values are numbers; check if they are nan and
 216         // use strict equality otherwise.
 217         return isNan($1) && isNan($2) || $1 === $2;
 218       } else {
 219         // The provided values are not numbers; use strict equality.
 220         return $1 === $2;
 221       }
 222     },
 223     toIndex: ($) => {
 224       const integer = floor($);
 225       if (isNan(integer) || integer == 0) {
 226         // The value is zero·like.
 227         return 0;
 228       } else {
 229         // The value is not zero·like.
 230         const clamped = toLength(integer);
 231         if (clamped !== integer) {
 232           // Clamping the value changes it.
 233           throw new RangeError(`Piscēs: Index out of range: ${$}.`);
 234         } else {
 235           // The value is within appropriate bounds.
 236           return integer;
 237         }
 238       }
 239     },
 240     toLength: ($) => {
 241       const len = floor($);
 242       return isNan(len) || len == 0
 243         ? 0
 244         : max(min(len, MAXIMUM_SAFE_INTEGRAL_NUMBER), 0);
 245     },
 246   };
 247 })();
 248
 249 /**
 250  * Returns a lowercase string identifying the type of the provided
 251  * value.
 252  *
 253  * This differs from the value of the `typeof` operator only in the
 254  * cases of objects and null.
 255  */
 256 export const type = ($) => {
 257   if ($ === null) {
 258     // The provided value is null.
 259     return "null";
 260   } else {
 261     // The provided value is not null.
 262     const type·of = typeof $;
 263     return type·of === "function" ? "object" : type·of;
 264   }
 265 };