viperjs 0.2.2

An embeddable JavaScript engine in safe Rust, with zero runtime dependencies.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
//! §20.3 `Boolean` and §21.1 `Number` — the two constructors that wrap a primitive.
//!
//! # What a wrapper is for
//!
//! `ToObject` (§7.1.18). A primitive has no properties of its own, so every operation that needs
//! an object out of one makes a wrapper: `Object(1)`, a method called with a primitive receiver in
//! sloppy code, a `for`-`in` over a String. The wrapper is an ordinary object with an ordinary
//! prototype that happens to remember what it was made from, and the prototype's methods are the
//! only things that read it.
//!
//! # Why one slot serves both
//!
//! §20.3 calls it `[[BooleanData]]` and §21.1 calls it `[[NumberData]]`, and a method of one may
//! not read the other's — `Boolean.prototype.valueOf.call(new Number(1))` is a TypeError. ViperJS
//! keeps one slot holding the primitive, and *the value says which*: a `Value::Boolean` is a
//! `[[BooleanData]]` and can be nothing else. So the rule is enforced by matching on what is
//! there rather than by three fields that could each be set wrongly.

use super::{define_function_metadata, define_method, define_value};
use crate::heap::{Heap, NativeCall, ObjectId};
use crate::realm::Realm;
use crate::value::{Abrupt, Completion, Value, number_to_string};
use crate::vm::Vm;

/// Build `Boolean` and `Number` into `heap`.
pub fn install(heap: &mut Heap, realm: &Realm, global: ObjectId) {
    let boolean_prototype = realm.boolean_prototype();
    let boolean = constructor(
        heap,
        realm,
        global,
        "Boolean",
        1,
        boolean_prototype,
        make_boolean,
    );
    let _ = boolean;
    define_method(
        heap,
        realm,
        boolean_prototype,
        "toString",
        0,
        boolean_to_string,
    );
    define_method(
        heap,
        realm,
        boolean_prototype,
        "valueOf",
        0,
        boolean_value_of,
    );

    let number_prototype = realm.number_prototype();
    let number = constructor(
        heap,
        realm,
        global,
        "Number",
        1,
        number_prototype,
        make_number,
    );
    define_method(
        heap,
        realm,
        number_prototype,
        "toString",
        1,
        number_to_string_method,
    );
    define_method(heap, realm, number_prototype, "valueOf", 0, number_value_of);
    // §21.1.3.2, §21.1.3.3 and §21.1.3.5 — the three spellings that need exact decimals.
    super::number_format::install(heap, realm, number_prototype);
    define_method(
        heap,
        realm,
        number_prototype,
        "toLocaleString",
        0,
        number_to_locale_string,
    );

    // §21.1.2 — the constants, none of them writable, enumerable or configurable.
    for (name, value) in [
        ("EPSILON", f64::EPSILON),
        ("MAX_SAFE_INTEGER", 9_007_199_254_740_991.0),
        ("MAX_VALUE", f64::MAX),
        ("MIN_SAFE_INTEGER", -9_007_199_254_740_991.0),
        ("MIN_VALUE", 5e-324),
        ("NaN", f64::NAN),
        ("NEGATIVE_INFINITY", f64::NEG_INFINITY),
        ("POSITIVE_INFINITY", f64::INFINITY),
    ] {
        super::define_fixed(heap, number, name, Value::Number(value));
    }
    for (name, length, native) in [
        ("isFinite", 1, is_finite as crate::heap::Native),
        ("isInteger", 1, is_integer),
        ("isNaN", 1, is_nan),
        ("isSafeInteger", 1, is_safe_integer),
    ] {
        define_method(heap, realm, number, name, length, native);
    }
    // §21.1.2.12 and §21.1.2.13 — `Number.parseFloat` **is** `%parseFloat%` and `Number.parseInt`
    // **is** `%parseInt%`. The same function object and not a second one with the same body, which
    // a program can see: `Number.parseFloat === parseFloat` is `true`, and installing a copy would
    // answer `false` while every other test passed.
    //
    // Read off the global rather than made here, because §19.2.4 made them and `global::install`
    // has already run. Silently skipped if it has not — an `Option` here would be a placeholder
    // that a script could reach.
    for name in ["parseFloat", "parseInt"] {
        if let Some(found) = super::own_value(heap, global, name) {
            super::define_value(heap, number, name, found);
        }
    }
}

/// One constructor, with its `prototype` and that prototype's `constructor` back.
fn constructor(
    heap: &mut Heap,
    realm: &Realm,
    global: ObjectId,
    name: &str,
    length: u32,
    prototype: ObjectId,
    native: crate::heap::Native,
) -> ObjectId {
    // §20.3.2 and §21.1.2 — `Boolean` and `Number` are constructors; everything this file
    // installs beside them is a method and is not.
    let function = heap.new_native_constructor(realm.function_prototype(), native);
    define_function_metadata(heap, function, name, length);
    // §20.3.2.1 and §21.1.2.15 — the `prototype` of a wrapper constructor is fixed in place, as
    // every constructor's is: an instance already inherits from it by the time a script could
    // move it.
    super::define_fixed(heap, function, "prototype", Value::Object(prototype));
    define_value(heap, prototype, "constructor", Value::Object(function));
    define_value(heap, global, name, Value::Object(function));
    function
}

/// §20.3.1.1 `Boolean(value)` — and `new Boolean(value)`, which differ in what they answer.
///
/// Called, it converts; constructed, it wraps. That is the whole of the difference, and it is why
/// `if (new Boolean(false))` takes the branch: the wrapper is an object, and every object is
/// truthy however it was made.
fn make_boolean(vm: &mut Vm, heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    let value = Value::Boolean(call.argument(0).to_boolean(heap));
    Ok(wrap_or_convert(
        vm,
        heap,
        call,
        value,
        vm.realm().boolean_prototype(),
    ))
}

/// §21.1.1.1 `Number(value)` and `new Number(value)`.
fn make_number(vm: &mut Vm, heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    // §21.1.1.1 step 1 — with no argument at all the answer is `+0`, which is not the same as
    // `ToNumber(undefined)` and is why `Number()` is `0` where `Number(undefined)` is `NaN`.
    //
    // And step 1.a is **`ToNumeric`**, not `ToNumber`. That one word is the only place in the
    // language where a BigInt becomes a Number without the program saying so a second time: §7.1.4
    // refuses one outright, which is what keeps `1n + 1` and `Math.abs(1n)` TypeErrors, and step
    // 1.b then converts what `ToNumeric` handed back. So `Number(1n)` is 1 and `+1n` is a
    // TypeError, from operations that look interchangeable and are not.
    let value = match call.arguments.first() {
        Some(argument) => Value::Number(match vm.to_numeric_value(*argument, heap)? {
            crate::heap::Numeric::Number(number) => number,
            // Step 1.b's `𝔽(ℝ(prim))` — the *nearest* Number, so a BigInt past 2^53 loses the
            // precision a BigInt exists to keep. That is the conversion, not a failure of it.
            crate::heap::Numeric::BigInt(big) => big.to_f64(),
        }),
        None => Value::Number(0.0),
    };
    Ok(wrap_or_convert(
        vm,
        heap,
        call,
        value,
        vm.realm().number_prototype(),
    ))
}

/// The shape both constructors share: a wrapper when constructed, the primitive when called.
fn wrap_or_convert(
    _vm: &mut Vm,
    heap: &mut Heap,
    call: &NativeCall<'_>,
    value: Value,
    prototype: ObjectId,
) -> Value {
    match call.constructing() {
        // §10.1.13 again — the prototype comes from new.target, so `class D extends Number {}`
        // makes wrappers that inherit `D.prototype`. The intrinsic passed in is the default.
        true => {
            let prototype = super::prototype_from(heap, call, prototype);
            Value::Object(heap.new_wrapper(prototype, value))
        }
        false => value,
    }
}

/// `thisBooleanValue` (§20.3.3) and `thisNumberValue` (§21.1.3) — the receiver's own primitive.
///
/// A primitive receiver answers itself; a wrapper answers what it wraps; anything else is a
/// TypeError. The `matches` on the value is what keeps the two kinds apart — a Number wrapper
/// reaching `Boolean.prototype.valueOf` finds a `Value::Number` where it wanted a `Value::Boolean`
/// and is refused, which is what §20.3.3 asks for.
fn this_primitive(
    heap: &Heap,
    receiver: Value,
    wanted: fn(&Value) -> bool,
    complaint: &'static str,
) -> Completion<Value> {
    if wanted(&receiver) {
        return Ok(receiver);
    }
    if let Value::Object(object) = receiver
        && let Some(primitive) = heap.object(object).and_then(crate::heap::Object::primitive)
        && wanted(&primitive)
    {
        return Ok(primitive);
    }
    Err(Abrupt::type_error(complaint))
}

/// §20.3.3.2 `Boolean.prototype.toString`.
fn boolean_to_string(_vm: &mut Vm, heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    let value = this_primitive(
        heap,
        call.this_value,
        |value| matches!(value, Value::Boolean(_)),
        "Boolean.prototype.toString requires a boolean",
    )?;
    let text = matches!(value, Value::Boolean(true));
    Ok(super::text(heap, if text { "true" } else { "false" }))
}

/// §20.3.3.3 `Boolean.prototype.valueOf`.
fn boolean_value_of(_vm: &mut Vm, heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    this_primitive(
        heap,
        call.this_value,
        |value| matches!(value, Value::Boolean(_)),
        "Boolean.prototype.valueOf requires a boolean",
    )
}

/// §21.1.3.7 `Number.prototype.valueOf`.
fn number_value_of(_vm: &mut Vm, heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    this_primitive(
        heap,
        call.this_value,
        |value| matches!(value, Value::Number(_)),
        "Number.prototype.valueOf requires a number",
    )
}

/// §21.1.3.4 `Number.prototype.toLocaleString`.
///
/// Without ECMA-402 there is no locale to be aware of, so this is `toString` with no radix — which
/// §21.1.3.4's note allows outright. Its own function rather than an alias of `toString`, because
/// the two are distinct objects that a program can compare.
fn number_to_locale_string(
    vm: &mut Vm,
    heap: &mut Heap,
    call: &NativeCall<'_>,
) -> Completion<Value> {
    number_to_string_method(vm, heap, call)
}

/// §21.1.3.6 `Number.prototype.toString([radix])`.
fn number_to_string_method(
    _vm: &mut Vm,
    heap: &mut Heap,
    call: &NativeCall<'_>,
) -> Completion<Value> {
    let value = this_primitive(
        heap,
        call.this_value,
        |value| matches!(value, Value::Number(_)),
        "Number.prototype.toString requires a number",
    )?;
    let Value::Number(number) = value else {
        return Err(Abrupt::type_error(
            "Number.prototype.toString requires a number",
        ));
    };
    // Step 2 — a missing radix is 10, and `undefined` is *also* 10, which is why the argument is
    // asked about rather than converted blindly.
    let radix = match call.argument(0) {
        Value::Undefined => 10.0,
        given => given.to_integer_or_infinity(heap)?,
    };
    // Step 3 — anything outside 2 to 36 is a RangeError, including a fractional radix, which the
    // conversion above has already flattened.
    if !(2.0..=36.0).contains(&radix) {
        return Err(Abrupt::range_error("the radix must be between 2 and 36"));
    }
    let text = match radix as u32 {
        // §6.1.6.1.20's `Number::toString`, which is a different algorithm from the general one
        // and the only one that is exactly specified.
        10 => number_to_string(number),
        radix => in_radix(number, radix),
    };
    Ok(super::text(heap, &text))
}

/// A Number written in a radix other than ten — §21.1.3.6's implementation-approximated half.
///
/// The specification leaves this to the implementation past the point where a value is exactly
/// representable, and says only that it should be the digits of a value "for which x is closest".
/// Written the boring way: the integer part by repeated division, the fraction by repeated
/// multiplication, stopping when nothing is left or when a `f64` has no more to give.
fn in_radix(value: f64, radix: u32) -> String {
    if value.is_nan() {
        return "NaN".into();
    }
    if value.is_infinite() {
        // `==` and not `>`: only an infinity reaches here, so a comparison against zero would
        // be one no input could answer differently either way.
        return if value == f64::INFINITY {
            "Infinity"
        } else {
            "-Infinity"
        }
        .into();
    }
    // No case for zero: it falls through with nothing before the point and nothing after, and the
    // loop below writes the `0` that leaves. A branch for it would be one no input could tell from
    // its absence.
    const DIGITS: &[u8] = b"0123456789abcdefghijklmnopqrstuvwxyz";
    let negative = value < 0.0;
    let value = value.abs();
    let mut integer = value.trunc();
    let mut fraction = value.fract();

    let mut whole = Vec::new();
    while integer >= 1.0 {
        let digit = (integer % f64::from(radix)) as usize;
        whole.push(DIGITS[digit.min(35)]);
        integer = (integer / f64::from(radix)).trunc();
    }
    if whole.is_empty() {
        whole.push(b'0');
    }
    whole.reverse();
    let mut out = String::from_utf8_lossy(&whole).into_owned();

    if fraction > 0.0 {
        out.push('.');
        // Twenty digits is past what a `f64` can distinguish in any radix — the mantissa is 53
        // bits, and even in base 2 the fraction runs out well before this.
        for _ in 0..1100 {
            if fraction == 0.0 {
                break;
            }
            fraction *= f64::from(radix);
            let digit = fraction.trunc() as usize;
            out.push(char::from(DIGITS[digit.min(35)]));
            fraction = fraction.fract();
        }
    }
    if negative { format!("-{out}") } else { out }
}

/// §21.1.2.2 `Number.isFinite` — with **no** conversion, which is the whole point of it.
///
/// `isFinite("1")` is true and `Number.isFinite("1")` is false: the global one converts and this
/// one asks. That is why these four cannot share an implementation with anything.
fn is_finite(_vm: &mut Vm, _heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    Ok(Value::Boolean(matches!(
        call.argument(0),
        Value::Number(value) if value.is_finite()
    )))
}

/// §21.1.2.3 `Number.isInteger`.
fn is_integer(_vm: &mut Vm, _heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    Ok(Value::Boolean(matches!(
        call.argument(0),
        Value::Number(value) if value.is_finite() && value.trunc() == value
    )))
}

/// §21.1.2.4 `Number.isNaN`.
fn is_nan(_vm: &mut Vm, _heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    Ok(Value::Boolean(matches!(
        call.argument(0),
        Value::Number(value) if value.is_nan()
    )))
}

/// §21.1.2.5 `Number.isSafeInteger` — an integer every `f64` can tell from its neighbours.
fn is_safe_integer(_vm: &mut Vm, _heap: &mut Heap, call: &NativeCall<'_>) -> Completion<Value> {
    Ok(Value::Boolean(matches!(
        call.argument(0),
        Value::Number(value)
            if value.is_finite() && value.trunc() == value && value.abs() <= 9_007_199_254_740_991.0
    )))
}