]> Lady’s Gitweb - Pisces/blob - function.js
efb3871e071040212cde3a0bc9386a90064c294c
[Pisces] / 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 );
This page took 0.059759 seconds and 3 git commands to generate.