[Pisces] / function.js

// ♓🌟 Piscēs ∷ function.js
// ====================================================================
//
// 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/>.

import { ITERATOR } from "./value.js";

export const {
  /**
   * Creates a bound function from the provided function using the
   * provided this value and arguments list.
   *
   * ☡ As with `call` and `construct`, the arguments must be passed as
   * an array.
   */
  bind,

  /**
   * Returns a new function which calls the provided function with its
   * first argument as the `this` value and the remaining arguments
   * passed through.
   *
   * ※ This is effectively an alias for `Function::call.bind`.
   */
  makeCallable,

  /**
   * Returns a constructor which throws whenever it is called but has
   * the same `.name` and `.prototype` as the provided value.
   *
   * If a second argument is provided, the returned constructor will
   * use that as its prototype; otherwise, it will use the prototype of
   * the provided value.
   */
  makeIllegalConstructor,
} = (() => {
  // ☡ Because these functions are used to initialize module constants,
  // they can’t depend on imports from elsewhere.
  const {
    bind: functionBind,
    call: functionCall,
  } = Function.prototype;
  const callBind = Reflect.apply(functionBind, functionCall, [
    functionBind,
  ]);
  const {
    create: objectCreate,
    defineProperties: defineOwnProperties,
    getPrototypeOf: getPrototype,
    setPrototypeOf: setPrototype,
  } = Object;
  const { [ITERATOR]: arrayIterator } = Array.prototype;
  const {
    next: arrayIteratorNext,
  } = getPrototype([][ITERATOR]());
  const argumentIterablePrototype = {
    [ITERATOR]() {
      return {
        next: callBind(
          arrayIteratorNext,
          call(arrayIterator, this.args, []),
        ),
      };
    },
  };
  return {
    bind: ($, boundThis, boundArgs) =>
      callBind(
        $,
        boundThis,
        ...objectCreate(
          argumentIterablePrototype,
          { args: { value: boundArgs } },
        ),
      ),
    makeCallable: ($, name = undefined) =>
      defineOwnProperties(callBind(functionCall, $), {
        length: { value: $.length + 1 },
        name: { value: name ?? $.name ?? "" },
      }),
    makeIllegalConstructor: ($, proto = undefined) => {
      const constructor = function () {
        throw new TypeError("Illegal constructor");
      };
      if ($ == null && proto === undefined) {
        // The provided argument is nullish and no explicit prototype
        // was provided.
        //
        // Do not modify the prototype of the generated constructor.
        /* do nothing */
      } else {
        // The provided argument is not nullish or an explicit
        // prototype was provided.
        //
        // Set the prototype of the generated constructor to match.
        setPrototype(
          constructor,
          proto === undefined ? getPrototype($) : proto,
        );
      }
      return defineOwnProperties(constructor, {
        name: { value: $?.name ?? "" },
        prototype: { value: $?.prototype ?? {}, writable: false },
      });
    },
  };
})();

export const {
  /**
   * Calls the provided function with the provided this value and
   * arguments list.
   *
   * ☡ This is effectively an alias for `Reflect.apply`—the arguments
   * must be passed as an arraylike.
   */
  call,

  /**
   * Constructs the provided function with the provided arguments list
   * and new target.
   *
   * ☡ This is effectively an alias for `Reflect.construct`—the
   * arguments must be passed as an arraylike.
   */
  construct,

  /** Returns whether the provided value is a constructor. */
  isConstructor,
} = (() => {
  const { apply, construct } = Reflect;
  return {
    call: (target, thisArgument, argumentsList) =>
      apply(target, thisArgument, argumentsList),
    construct: (target, argumentsList, ...args) =>
      args.length > 0
        ? construct(target, argumentsList, args[0])
        : construct(target, argumentsList),
    isConstructor: ($) =>
      completesNormally(() =>
        // Try constructing a new object with the provided value as its
        // `new.target`. This will throw if the provided value is not a
        // constructor.
        construct(function () {}, [], $)
      ),
  };
})();

/**
 * Returns whether calling the provided function with no `this` value
 * or arguments completes normally; that is, does not throw an error.
 *
 * ☡ This function will throw an error if the provided argument is not
 * callable.
 */
export const completesNormally = ($) => {
  if (!isCallable($)) {
    // The provided value is not callable; this is an error.
    throw new TypeError(
      `Piscēs: Cannot determine completion of noncallable value: ${$}`,
    );
  } else {
    // The provided value is callable.
    try {
      // Attempt to call the function and return true if this succeeds.
      $();
      return true;
    } catch {
      // Calling the function did not succeed; return false.
      return false;
    }
  }
};

/**
 * Returns the provided value.
 *
 * ※ This function can be called as a constructor. When used in an
 * `extends` clause and called via `super`, it will set the value of
 * `this` to the provided value, enabling it to be extended with
 * private class features.
 */
export const identity = function ($) {
  return $;
};

/** Returns whether the provided value is callable. */
export const isCallable = ($) => typeof $ === "function";

/**
 * Returns whether the provided object inherits from the prototype of
 * the provided function.
 */
export const ordinaryHasInstance = makeCallable(
  Function.prototype[Symbol.hasInstance],
  "ordinaryHasInstance",
);