Build function.js on top of object.js infra

[Pisces] / function.js

diff --git a/function.js b/function.js
index 72b3b0d69aa940190b7c85f79cae72cb0893c38c..71e4d098d41dfbad04e954dfd42c06d552af1a38 100644 (file)
--- a/function.js
+++ b/function.js
@@ -7,15 +7,31 @@
 // 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/>.
 
 // 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";
+import {
+  ITERATOR,
+  toFunctionName,
+  toLength,
+  type,
+  UNDEFINED,
+} from "./value.js";
+import {
+  defineOwnDataProperty,
+  defineOwnProperties,
+  defineOwnProperty,
+  getOwnPropertyDescriptor,
+  getPrototype,
+  objectCreate,
+  setPropertyValues,
+  setPrototype,
+} from "./object.js";

 
 export const {
   /**
    * Creates a bound function from the provided function using the
    * provided this value and arguments list.
    *
 
 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.
+   * ☡ As with `call` and `construct`, the arguments must be passed as
+   * an array.

    */
   bind,
 
    */
   bind,
 


@@ -24,24 +40,77 @@ export const {
    * first argument as the `this` value and the remaining arguments
    * passed through.
    *
    * first argument as the `this` value and the remaining arguments
    * passed through.
    *

-   * ※ This is effectively an alias for Function.prototype.call.bind.
+   * The `length`, `name`, and prototype of the provided function will
+   * be preserved in the new one. A second argument may be used to
+   * override `length` and `name`.

    */
    */

-  makeCallable,
+  createArrowFunction,
+
+  /**
+   * Returns a new function which calls the provided function with its
+   * first argument as the `this` value and the remaining arguments
+   * passed through.
+   *
+   * The `length`, `name`, and prototype of the provided function will
+   * be preserved in the new one. A second argument may be used to
+   * override `length` and `name`.
+   *
+   * ※ This is effectively an alias for `Function::call.bind`.
+   */
+  createCallableFunction,
+
+  /**
+   * Returns a constructor which throws whenever it is called but has
+   * the same `.name` and `.prototype` as the provided value.
+   *
+   * The `length`, `name`, `prototype`, and prototype of the provided
+   * function will be preserved in the new one. A second argument may
+   * be used to override `length`, `name`, and `prototype`.
+   */
+  createIllegalConstructor,
+
+  /**
+   * Returns a constructor which produces a new constructor which wraps
+   * the provided constructor, but returns a proxy of the result using
+   * the provided handler.
+   *
+   * The resulting constructor inherits from, and has the same basic
+   * shape as, `Proxy`.
+   *
+   * If a base constructor is not provided, `Object` will be used.
+   *
+   * If a third argument is provided, it is used as the target for the
+   * provided constructor when it is constructed. This can be used to
+   * prevent leakage of the provided constructor to superclasses
+   * through `new.target`.
+   *
+   * The `length` of the provided function will be preserved in the new
+   * one. A fourth argument may be used to override `length` and
+   * `name`.
+   *
+   * ※ `.prototype` will be present, but undefined, on the resulting
+   * constructor. This differs from the behaviour of `Proxy`, for which
+   * `.prototype` is not present at all. It is not presently possible
+   * to create a constructor with no `.prototype` property in
+   * Ecmascript code.
+   */
+  createProxyConstructor,

 } = (() => {
 } = (() => {

-  // ☡ Because these functions are used to initialize module constants,
-  // they can’t depend on imports from elsewhere.
+  const { prototype: functionPrototype } = Function;

   const {
     bind: functionBind,
     call: functionCall,
   const {
     bind: functionBind,
     call: functionCall,

-  } = Function.prototype;
-  const callBind = Reflect.apply(functionBind, functionCall, [
+  } = functionPrototype;
+  const objectConstructor = Object;
+  const proxyConstructor = Proxy;
+  const {
+    apply: reflectApply,
+    construct: reflectConstruct,
+  } = Reflect;
+  const callBind = reflectApply(functionBind, functionCall, [

     functionBind,
   ]);
     functionBind,
   ]);

-  const {
-    create: objectCreate,
-    defineProperty: defineOwnProperty,
-    getPrototypeOf: getPrototype,
-  } = Object;
+  const { revocable } = Proxy;

   const { [ITERATOR]: arrayIterator } = Array.prototype;
   const {
     next: arrayIteratorNext,
   const { [ITERATOR]: arrayIterator } = Array.prototype;
   const {
     next: arrayIteratorNext,


@@ -49,6 +118,9 @@ export const {
   const argumentIterablePrototype = {
     [ITERATOR]() {
       return {
   const argumentIterablePrototype = {
     [ITERATOR]() {
       return {

+        [ITERATOR]() {
+          return this;
+        },

         next: callBind(
           arrayIteratorNext,
           call(arrayIterator, this.args, []),
         next: callBind(
           arrayIteratorNext,
           call(arrayIterator, this.args, []),


@@ -56,22 +128,226 @@ export const {
       };
     },
   };
       };
     },
   };

+  const applyBaseFunction = ($, base, lengthDelta = 0) => {
+    if (base === UNDEFINED) {
+      // No base function was provided to apply.
+      return $;
+    } else {
+      // A base function was provided; apply it.
+      const { length, name, prototype } = base;
+      if (getPrototype($) === functionPrototype) {
+        setPrototype($, getPrototype(base));
+      } else {
+        /* do nothing */
+      }
+      return applyProperties($, {
+        length: +length + lengthDelta,
+        name,
+        prototype,
+      });
+    }
+  };
+  const applyProperties = ($, override) => {
+    if (override === UNDEFINED) {
+      // No properties were provided to apply.
+      return $;
+    } else {
+      // Properties were provided; apply them.
+      const { length, name, prototype } = override;
+      if (
+        prototype === UNDEFINED ||
+        !getOwnPropertyDescriptor($, "prototype")?.writable
+      ) {
+        // The provided function has no `.prototype`, its prototype is
+        // not writable, or no prototype value was provided.
+        //
+        // Do not modify the prototype property of the provided
+        // function.
+        /* do nothing */
+      } else {
+        // The provided function is a constructor and a prototype value
+        // was provided.
+        //
+        // Change the prototype property of the provided function to
+        // match.
+        defineOwnProperty(
+          $,
+          "prototype",
+          defineOwnDataProperty(
+            objectCreate(null),
+            "value",
+            prototype,
+          ),
+        );
+      }
+      return defineOwnProperties($, {
+        length: defineOwnDataProperty(
+          objectCreate(null),
+          "value",
+          toLength(length === UNDEFINED ? $.length : length),
+        ),
+        name: defineOwnDataProperty(
+          objectCreate(null),
+          "value",
+          toFunctionName(name === UNDEFINED ? $.name ?? "" : name),
+        ),
+      });
+    }
+  };
+

   return {
     bind: ($, boundThis, boundArgs) =>
       callBind(
         $,
         boundThis,
   return {
     bind: ($, boundThis, boundArgs) =>
       callBind(
         $,
         boundThis,

-        ...objectCreate(
-          argumentIterablePrototype,
-          { args: { value: boundArgs } },
+        ...defineOwnDataProperty(
+          objectCreate(argumentIterablePrototype),
+          "args",
+          boundArgs,

         ),
       ),
         ),
       ),

-    makeCallable: ($) =>
+    createArrowFunction: ($, propertyOverride = UNDEFINED) =>
+      applyProperties(
+        applyBaseFunction(
+          (...$s) => reflectApply($, UNDEFINED, $s),
+          $,
+        ),
+        propertyOverride,
+      ),
+    createCallableFunction: ($, propertyOverride = UNDEFINED) =>
+      applyProperties(
+        applyBaseFunction(
+          (...$s) => {
+            const iterator = defineOwnDataProperty(
+              objectCreate(argumentIterablePrototype),
+              "args",
+              $s,
+            )[ITERATOR]();
+            const { value: thisValue } = iterator.next();
+            return reflectApply($, thisValue, [...iterator]);
+          },
+          $,
+          1,
+        ),
+        propertyOverride,
+      ),
+    createIllegalConstructor: ($, propertyOverride = UNDEFINED) =>

       defineOwnProperty(
       defineOwnProperty(

-        callBind(functionCall, $),
-        "length",
-        { value: $.length + 1 },
+        applyProperties(
+          applyBaseFunction(
+            function () {
+              throw new TypeError("Illegal constructor");
+            },
+            $,
+          ),
+          propertyOverride,
+        ),
+        "prototype",
+        { writable: false },

       ),
       ),

+    createProxyConstructor: (
+      handler,
+      $,
+      newTarget = UNDEFINED,
+      propertyOverride = UNDEFINED,
+    ) => {
+      const constructor = $ === UNDEFINED ? objectConstructor : $;
+      const target = newTarget === UNDEFINED ? constructor : newTarget;
+      const len = toLength(constructor.length);
+      if (!(type(handler) === "object")) {
+        // The provided handler is not an object; this is an error.
+        throw new TypeError(
+          `Piscēs: Proxy handler must be an object, but got: ${handler}.`,
+        );
+      } else if (!isConstructor(constructor)) {
+        // The provided constructor is not a constructor; this is an
+        // error.
+        throw new TypeError(
+          "Piscēs: Cannot create proxy constructor from nonconstructible value.",
+        );
+      } else if (!isConstructor(target)) {
+        // The provided new target is not a constructor; this is an
+        // error.
+        throw new TypeError(
+          "Piscēs: New target must be a constructor.",
+        );
+      } else {
+        // The arguments are acceptable.
+        return applyProperties(
+          defineOwnProperties(
+            setPrototype(
+              function C(...$s) {
+                if (new.target === UNDEFINED) {
+                  // The constructor was not called with new; this is
+                  // an error.
+                  throw new TypeError(
+                    `Piscēs: ${
+                      C.name ?? "Proxy"
+                    } must be called with new.`,
+                  );
+                } else {
+                  // The constructor was called with new; return the
+                  // appropriate proxy.
+                  const O = reflectConstruct(
+                    constructor,
+                    $s,
+                    target,
+                  );
+                  return new proxyConstructor(O, handler);
+                }
+              },
+              proxyConstructor,
+            ),
+            {
+              length: defineOwnDataProperty(
+                objectCreate(null),
+                "value",
+                len,
+              ),
+              name: defineOwnDataProperty(
+                objectCreate(null),
+                "value",
+                `${toFunctionName(constructor.name ?? "")}Proxy`,
+              ),
+              prototype: setPropertyValues(objectCreate(null), {
+                configurable: false,
+                enumerable: false,
+                value: UNDEFINED,
+                writable: false,
+              }),
+              revocable: setPropertyValues(objectCreate(null), {
+                configurable: true,
+                enumerable: false,
+                value: defineOwnProperties(
+                  (...$s) => {
+                    const O = reflectConstruct(
+                      constructor,
+                      $s,
+                      target,
+                    );
+                    return revocable(O, handler);
+                  },
+                  {
+                    length: defineOwnDataProperty(
+                      objectCreate(null),
+                      "value",
+                      len,
+                    ),
+                    name: defineOwnDataProperty(
+                      objectCreate(null),
+                      "value",
+                      "revocable",
+                    ),
+                  },
+                ),
+                writable: true,
+              }),
+            },
+          ),
+          propertyOverride,
+        );
+      }
+    },

   };
 })();
 
   };
 })();
 


@@ -79,19 +355,47 @@ export const {
  * Calls the provided function with the provided this value and
  * arguments list.
  *
  * Calls the provided function with the provided this value and
  * arguments list.
  *

- * ☡ This is an alias for Reflect.apply—the arguments must be passed
- * as an array.
+ * ☡ This is effectively an alias for `Reflect.apply`—the arguments
+ * must be passed as an arraylike.
+ */
+export const call = createArrowFunction(Reflect.apply, {
+  name: "call",
+});
+
+/**
+ * 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 call = Reflect.apply;
+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;
+    }
+  }
+};

 
 /**
  * Constructs the provided function with the provided arguments list
  * and new target.
  *
 
 /**
  * Constructs the provided function with the provided arguments list
  * and new target.
  *

- * ☡ This is an alias for Reflect.construct—the arguments must be
- * passed as an array.
+ * ☡ This is effectively an alias for `Reflect.construct`—the
+ * arguments must be passed as an arraylike.

  */
  */

-export const construct = Reflect.construct;
+export const construct = createArrowFunction(Reflect.construct);

 
 /**
  * Returns the provided value.
 
 /**
  * Returns the provided value.


@@ -109,24 +413,19 @@ export const identity = function ($) {
 export const isCallable = ($) => typeof $ === "function";
 
 /** Returns whether the provided value is a constructor. */
 export const isCallable = ($) => typeof $ === "function";
 
 /** Returns whether the provided value is a constructor. */

-export const isConstructor = ($) => {
-  // The provided value is an object.
-  try {
-    construct(
-      function () {},
-      [],
-      $,
-    ); // will throw if $ is not a constructor
-    return true;
-  } catch {
-    return false;
-  }
-};
+export const 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 the provided object inherits from the prototype of
  * the provided function.
  */
 
 /**
  * Returns whether the provided object inherits from the prototype of
  * the provided function.
  */

-export const ordinaryHasInstance = makeCallable(
+export const ordinaryHasInstance = createCallableFunction(

   Function.prototype[Symbol.hasInstance],
   Function.prototype[Symbol.hasInstance],

+  { name: "ordinaryHasInstance" },

 );
 );