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

   1 // ♓🌟 Piscēs ∷ function.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 import { ITERATOR } from "./value.js";
  11
  12 export const {
  13   /**
  14    * Creates a bound function from the provided function using the
  15    * provided this value and arguments list.
  16    *
  17    * ☡ As with `call` and `construct`, the arguments must be passed as
  18    * an array.
  19    */
  20   bind,
  21
  22   /**
  23    * Returns a new function which calls the provided function with its
  24    * first argument as the `this` value and the remaining arguments
  25    * passed through.
  26    *
  27    * ※ This is effectively an alias for `Function::call.bind`.
  28    */
  29   makeCallable,
  30 } = (() => {
  31   // ☡ Because these functions are used to initialize module constants,
  32   // they can’t depend on imports from elsewhere.
  33   const {
  34     bind: functionBind,
  35     call: functionCall,
  36   } = Function.prototype;
  37   const callBind = Reflect.apply(functionBind, functionCall, [
  38     functionBind,
  39   ]);
  40   const {
  41     create: objectCreate,
  42     defineProperty: defineOwnProperty,
  43     getPrototypeOf: getPrototype,
  44   } = Object;
  45   const { [ITERATOR]: arrayIterator } = Array.prototype;
  46   const {
  47     next: arrayIteratorNext,
  48   } = getPrototype([][ITERATOR]());
  49   const argumentIterablePrototype = {
  50     [ITERATOR]() {
  51       return {
  52         next: callBind(
  53           arrayIteratorNext,
  54           call(arrayIterator, this.args, []),
  55         ),
  56       };
  57     },
  58   };
  59   return {
  60     bind: ($, boundThis, boundArgs) =>
  61       callBind(
  62         $,
  63         boundThis,
  64         ...objectCreate(
  65           argumentIterablePrototype,
  66           { args: { value: boundArgs } },
  67         ),
  68       ),
  69     makeCallable: ($) =>
  70       defineOwnProperty(
  71         callBind(functionCall, $),
  72         "length",
  73         { value: $.length + 1 },
  74       ),
  75   };
  76 })();
  77
  78 export const {
  79   /**
  80    * Calls the provided function with the provided this value and
  81    * arguments list.
  82    *
  83    * ☡ This is an alias for `Reflect.apply`—the arguments must be
  84    * passed as an arraylike.
  85    */
  86   apply: call,
  87
  88   /**
  89    * Constructs the provided function with the provided arguments list
  90    * and new target.
  91    *
  92    * ☡ This is an alias for `Reflect.construct`—the arguments must be
  93    * passed as an arraylike.
  94    */
  95   construct,
  96 } = Reflect;
  97
  98 /**
  99  * Returns whether calling the provided function with no `this` value
 100  * or arguments completes normally; that is, does not throw an error.
 101  *
 102  * ☡ This function will throw an error if the provided argument is not
 103  * callable.
 104  */
 105 export const completesNormally = ($) => {
 106   if (!isCallable($)) {
 107     // The provided value is not callable; this is an error.
 108     throw new TypeError(
 109       `Piscēs: Cannot determine completion of noncallable value: ${$}`,
 110     );
 111   } else {
 112     // The provided value is callable.
 113     try {
 114       // Attempt to call the function and return true if this succeeds.
 115       $();
 116       return true;
 117     } catch {
 118       // Calling the function did not succeed; return false.
 119       return false;
 120     }
 121   }
 122 };
 123
 124 /**
 125  * Returns the provided value.
 126  *
 127  * ※ This function can be called as a constructor. When used in an
 128  * `extends` clause and called via `super`, it will set the value of
 129  * `this` to the provided value, enabling it to be extended with
 130  * private class features.
 131  */
 132 export const identity = function ($) {
 133   return $;
 134 };
 135
 136 /** Returns whether the provided value is callable. */
 137 export const isCallable = ($) => typeof $ === "function";
 138
 139 /** Returns whether the provided value is a constructor. */
 140 export const isConstructor = ($) => {
 141   // The provided value is an object.
 142   try {
 143     // Try constructing a new object with the provided value as its
 144     // `new.target`. This will throw if the provided value is not a
 145     // constructor.
 146     construct(
 147       function () {},
 148       [],
 149       $,
 150     );
 151     return true;
 152   } catch {
 153     // The provided value was not a constructor.
 154     return false;
 155   }
 156 };
 157
 158 /**
 159  * Returns whether the provided object inherits from the prototype of
 160  * the provided function.
 161  */
 162 export const ordinaryHasInstance = makeCallable(
 163   Function.prototype[Symbol.hasInstance],
 164 );