Add completesNormally to function.js

[Pisces] / function.test.js

// ♓🌟 Piscēs ∷ function.test.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 {
  assertEquals,
  assertStrictEquals,
  assertThrows,
  describe,
  it,
} from "./dev-deps.js";
import {
  bind,
  call,
  completesNormally,
  construct,
  identity,
  isCallable,
  isConstructor,
  makeCallable,
  ordinaryHasInstance,
} from "./function.js";

describe("bind", () => {
  it("[[Call]] binds this", () => {
    assertStrictEquals(
      bind(
        function () {
          return this;
        },
        "pass",
        [],
      ).call("fail"),
      "pass",
    );
  });

  it("[[Call]] binds arguments", () => {
    assertEquals(
      bind(
        function (...args) {
          return [this, ...args];
        },
        "etaoin",
        ["shrdlu"],
      ).call("failure", "cmfwyp"),
      ["etaoin", "shrdlu", "cmfwyp"],
    );
  });

  it("[[Call]] works with any arraylike third argument", () => {
    assertEquals(
      bind(
        function (...args) {
          return [this, ...args];
        },
        "etaoin",
        {
          1: "shrdlu",
          3: "failure",
          length: 3,
        },
      ).call("failure", "cmfwyp"),
      ["etaoin", undefined, "shrdlu", undefined, "cmfwyp"],
    );
  });
});

describe("call", () => {
  it("[[Call]] calls with the provided this value", () => {
    assertStrictEquals(
      call(
        function () {
          return this;
        },
        "pass",
        [],
      ),
      "pass",
    );
  });

  it("[[Call]] calls with the provided arguments", () => {
    assertEquals(
      call(
        function (...args) {
          return [this, ...args];
        },
        "etaoin",
        ["shrdlu", "cmfwyp"],
      ),
      ["etaoin", "shrdlu", "cmfwyp"],
    );
  });

  it("[[Call]] works with any arraylike third argument", () => {
    assertEquals(
      call(
        function (...args) {
          return [this, ...args];
        },
        "etaoin",
        {
          1: "shrdlu",
          3: "cmfwyp",
          4: "failure",
          length: 4,
        },
      ),
      ["etaoin", undefined, "shrdlu", undefined, "cmfwyp"],
    );
  });
});

describe("completesNormally", () => {
  it("[[Call]] returns true for functions which complete normally", () => {
    assertStrictEquals(completesNormally(() => {}), true);
  });

  it("[[Call]] returns false for functions which throw", () => {
    assertStrictEquals(
      completesNormally(() => {
        throw null;
      }),
      false,
    );
  });

  it("[[Call]] throws when the argument is not callable", () => {
    assertThrows(() => {
      completesNormally(null);
    });
  });

  it("[[Call]] throws when the argument is not provided", () => {
    assertThrows(() => {
      completesNormally();
    });
  });
});

describe("construct", () => {
  it("[[Call]] defaults to the constructor as the target", () => {
    const constructor = class {};
    assertStrictEquals(
      Object.getPrototypeOf(construct(
        constructor,
        [],
      )),
      constructor.prototype,
    );
  });

  it("[[Call]] constructs with the provided new target", () => {
    const target = function () {};
    assertStrictEquals(
      construct(
        function () {
          return new.target;
        },
        [],
        target,
      ),
      target,
    );
  });

  it("[[Call]] constructs with the provided arguments", () => {
    assertEquals(
      construct(
        function (...args) {
          return [new.target.value, ...args];
        },
        ["shrdlu", "cmfwyp"],
        Object.assign(function () {}, { value: "etaoin" }),
      ),
      ["etaoin", "shrdlu", "cmfwyp"],
    );
  });

  it("[[Call]] works with any arraylike third argument", () => {
    assertEquals(
      construct(
        function (...args) {
          return [new.target.value, ...args];
        },
        {
          1: "shrdlu",
          3: "cmfwyp",
          4: "failure",
          length: 4,
        },
        Object.assign(function () {}, { value: "etaoin" }),
      ),
      ["etaoin", undefined, "shrdlu", undefined, "cmfwyp"],
    );
  });
});

describe("identity", () => {
  it("[[Call]] returns what it is given", () => {
    const value = {};
    assertStrictEquals(identity(value), value);
  });

  it("[[Construct]] is constructable", () => {
    const value = {};
    assertStrictEquals(new identity(value), value);
  });

  it("[[Construct]] is subclassable", () => {
    const value = {};
    assertStrictEquals(new class extends identity {}(value), value);
  });
});

describe("isCallable", () => {
  it("[[Call]] returns true for ordinary functions", () => {
    assertStrictEquals(isCallable(function () {}), true);
  });

  it("[[Call]] returns true for arrow functions", () => {
    assertStrictEquals(isCallable(() => {}), true);
  });

  it("[[Call]] returns true for generator functions", () => {
    assertStrictEquals(isCallable(function* () {}), true);
  });

  it("[[Call]] returns true for classes", () => {
    assertStrictEquals(isCallable(class {}), true);
  });

  it("[[Call]] returns true for builtin functions", () => {
    assertStrictEquals(isCallable(Math.ceil), true);
  });

  it("[[Call]] returns true for getters", () => {
    assertStrictEquals(
      isCallable(
        Object.getOwnPropertyDescriptor({
          get foo() {
            return undefined;
          },
        }, "foo").get,
      ),
      true,
    );
  });

  it("[[Call]] returns true for setters", () => {
    assertStrictEquals(
      isCallable(
        Object.getOwnPropertyDescriptor({
          set foo($) {
            /* do nothing */
          },
        }, "foo").set,
      ),
      true,
    );
  });

  it("[[Call]] returns false for null", () => {
    assertStrictEquals(isCallable(null), false);
  });

  it("[[Call]] returns false for objects", () => {
    assertStrictEquals(isCallable({}), false);
  });
});

describe("isConstructor", () => {
  it("[[Call]] returns true for ordinary functions", () => {
    assertStrictEquals(isConstructor(function () {}), true);
  });

  it("[[Call]] returns false for arrow functions", () => {
    assertStrictEquals(isConstructor(() => {}), false);
  });

  it("[[Call]] returns false for generator functions", () => {
    assertStrictEquals(isConstructor(function* () {}), false);
  });

  it("[[Call]] returns true for classes", () => {
    assertStrictEquals(isConstructor(class {}), true);
  });

  it("[[Call]] returns false for builtin functions", () => {
    assertStrictEquals(isConstructor(Math.ceil), false);
  });

  it("[[Call]] returns false for getters", () => {
    assertStrictEquals(
      isConstructor(
        Object.getOwnPropertyDescriptor({
          get foo() {
            return undefined;
          },
        }, "foo").get,
      ),
      false,
    );
  });

  it("[[Call]] returns false for setters", () => {
    assertStrictEquals(
      isConstructor(
        Object.getOwnPropertyDescriptor({
          set foo($) {
            /* do nothing */
          },
        }, "foo").set,
      ),
      false,
    );
  });

  it("[[Call]] returns false for null", () => {
    assertStrictEquals(isConstructor(null), false);
  });

  it("[[Call]] returns false for objects", () => {
    assertStrictEquals(isConstructor({}), false);
  });
});

describe("makeCallable", () => {
  it("[[Call]] transfers the first argument to this", () => {
    assertStrictEquals(
      makeCallable(
        function () {
          return this;
        },
      ).call("fail", "pass"),
      "pass",
    );
  });

  it("[[Call]] transfers the remaining arguments", () => {
    assertEquals(
      makeCallable(
        function (...args) {
          return [this, ...args];
        },
      ).call("failure", "etaoin", "shrdlu", "cmfwyp"),
      ["etaoin", "shrdlu", "cmfwyp"],
    );
  });
});

describe("ordinaryHasInstance", () => {
  it("[[Call]] walks the prototype chain", () => {
    const constructor = class {
      [Symbol.hasInstance]() {
        return false;
      }
    };
    assertStrictEquals(
      ordinaryHasInstance(
        constructor,
        new class extends constructor {}(),
      ),
      true,
    );
  });
});