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   createCallableFunction,
  30
  31   /**
  32    * Returns a constructor which throws whenever it is called but has
  33    * the same `.name` and `.prototype` as the provided value.
  34    *
  35    * If a second argument is provided, the returned constructor will
  36    * use that as its prototype; otherwise, it will use the prototype of
  37    * the provided value.
  38    */
  39   createIllegalConstructor,
  40
  41   /**
  42    * Returns a string function name generated from the provided value
  43    * and optional prefix.
  44    */
  45   toFunctionName,
  46 } = (() => {
  47   // ☡ Because these functions are used to initialize module constants,
  48   // they can’t depend on imports from elsewhere.
  49   const {
  50     bind: functionBind,
  51     call: functionCall,
  52   } = Function.prototype;
  53   const callBind = Reflect.apply(functionBind, functionCall, [
  54     functionBind,
  55   ]);
  56   const {
  57     create: objectCreate,
  58     defineProperties: defineOwnProperties,
  59     getOwnPropertyDescriptor,
  60     getPrototypeOf: getPrototype,
  61     setPrototypeOf: setPrototype,
  62   } = Object;
  63   const { [ITERATOR]: arrayIterator } = Array.prototype;
  64   const {
  65     next: arrayIteratorNext,
  66   } = getPrototype([][ITERATOR]());
  67   const argumentIterablePrototype = {
  68     [ITERATOR]() {
  69       return {
  70         next: callBind(
  71           arrayIteratorNext,
  72           call(arrayIterator, this.args, []),
  73         ),
  74       };
  75     },
  76   };
  77   const getSymbolDescription = getOwnPropertyDescriptor(
  78     Symbol.prototype,
  79     "description",
  80   ).get;
  81
  82   return {
  83     bind: ($, boundThis, boundArgs) =>
  84       callBind(
  85         $,
  86         boundThis,
  87         ...objectCreate(
  88           argumentIterablePrototype,
  89           { args: { value: boundArgs } },
  90         ),
  91       ),
  92     createCallableFunction: ($, name = undefined) =>
  93       defineOwnProperties(callBind(functionCall, $), {
  94         length: { value: $.length + 1 },
  95         name: {
  96           value: toFunctionName(
  97             name === undefined ? $.name ?? "" : name,
  98           ),
  99         },
 100       }),
 101     createIllegalConstructor: ($, proto = undefined) => {
 102       const constructor = function () {
 103         throw new TypeError("Illegal constructor");
 104       };
 105       if ($ == null && proto === undefined) {
 106         // The provided argument is nullish and no explicit prototype
 107         // was provided.
 108         //
 109         // Do not modify the prototype of the generated constructor.
 110         /* do nothing */
 111       } else {
 112         // The provided argument is not nullish or an explicit
 113         // prototype was provided.
 114         //
 115         // Set the prototype of the generated constructor to match.
 116         setPrototype(
 117           constructor,
 118           proto === undefined ? getPrototype($) : proto,
 119         );
 120       }
 121       return defineOwnProperties(constructor, {
 122         name: { value: $?.name ?? "" },
 123         prototype: { value: $?.prototype ?? {}, writable: false },
 124       });
 125     },
 126     toFunctionName: ($, prefix = undefined) => {
 127       const name = (() => {
 128         if (typeof $ === "symbol") {
 129           // The provided value is a symbol; format its description.
 130           const description = call(getSymbolDescription, $, []);
 131           return description === undefined ? "" : `[${description}]`;
 132         } else {
 133           // The provided value not a symbol; convert it to a string
 134           // property key.
 135           return `${$}`;
 136         }
 137       })();
 138       return prefix !== undefined ? `${prefix} ${name}` : name;
 139     },
 140   };
 141 })();
 142
 143 export const {
 144   /**
 145    * Calls the provided function with the provided this value and
 146    * arguments list.
 147    *
 148    * ☡ This is effectively an alias for `Reflect.apply`—the arguments
 149    * must be passed as an arraylike.
 150    */
 151   call,
 152
 153   /**
 154    * Constructs the provided function with the provided arguments list
 155    * and new target.
 156    *
 157    * ☡ This is effectively an alias for `Reflect.construct`—the
 158    * arguments must be passed as an arraylike.
 159    */
 160   construct,
 161
 162   /** Returns whether the provided value is a constructor. */
 163   isConstructor,
 164 } = (() => {
 165   const { apply, construct } = Reflect;
 166   return {
 167     call: (target, thisArgument, argumentsList) =>
 168       apply(target, thisArgument, argumentsList),
 169     construct: (target, argumentsList, ...args) =>
 170       args.length > 0
 171         ? construct(target, argumentsList, args[0])
 172         : construct(target, argumentsList),
 173     isConstructor: ($) =>
 174       completesNormally(() =>
 175         // Try constructing a new object with the provided value as its
 176         // `new.target`. This will throw if the provided value is not a
 177         // constructor.
 178         construct(function () {}, [], $)
 179       ),
 180   };
 181 })();
 182
 183 /**
 184  * Returns whether calling the provided function with no `this` value
 185  * or arguments completes normally; that is, does not throw an error.
 186  *
 187  * ☡ This function will throw an error if the provided argument is not
 188  * callable.
 189  */
 190 export const completesNormally = ($) => {
 191   if (!isCallable($)) {
 192     // The provided value is not callable; this is an error.
 193     throw new TypeError(
 194       `Piscēs: Cannot determine completion of noncallable value: ${$}`,
 195     );
 196   } else {
 197     // The provided value is callable.
 198     try {
 199       // Attempt to call the function and return true if this succeeds.
 200       $();
 201       return true;
 202     } catch {
 203       // Calling the function did not succeed; return false.
 204       return false;
 205     }
 206   }
 207 };
 208
 209 /**
 210  * Returns the provided value.
 211  *
 212  * ※ This function can be called as a constructor. When used in an
 213  * `extends` clause and called via `super`, it will set the value of
 214  * `this` to the provided value, enabling it to be extended with
 215  * private class features.
 216  */
 217 export const identity = function ($) {
 218   return $;
 219 };
 220
 221 /** Returns whether the provided value is callable. */
 222 export const isCallable = ($) => typeof $ === "function";
 223
 224 /**
 225  * Returns whether the provided object inherits from the prototype of
 226  * the provided function.
 227  */
 228 export const ordinaryHasInstance = createCallableFunction(
 229   Function.prototype[Symbol.hasInstance],
 230   "ordinaryHasInstance",
 231 );