nanvm_lib/vm/unstable/

mod.rs

#![doc = include_str!("README.md")]

use crate::{
    sign::Sign,
    vm::{
        Any, BigInt, Function, IVm, IteratorRecord, Number, String, ToAny, ToArray, ToObject,
        ToString, error,
    },
};

/// `v` spelled as ECMAScript's `Number::toString` does, the text a host puts
/// in a message when it names a number a program passed.
pub fn number_text(v: f64) -> std::string::String {
    crate::vm::string_coercion::number_text::<crate::naive::Naive>(v)
}

/// An `Any` holding the string `v`.
pub fn string_any<A: IVm>(v: &str) -> Any<A> {
    v.into()
}

/// An object property key.
pub fn string_key<A: IVm>(v: &str) -> String<A> {
    v.into()
}

/// An `Any` holding the string of UTF-16 code units `v`: the spelling of a
/// string no `&str` can hold, one with a lone surrogate.
pub fn string_any_utf16<A: IVm>(v: &[u16]) -> Any<A> {
    string_key_utf16::<A>(v).to_any()
}

/// An object property key of UTF-16 code units, for the same reason.
pub fn string_key_utf16<A: IVm>(v: &[u16]) -> String<A> {
    v.iter().copied().to_string()
}

/// An `Any` holding the bigint `v`.
pub fn bigint_any<A: IVm>(v: i64) -> Any<A> {
    Into::<BigInt<A>>::into(v).to_any()
}

/// An `Any` holding the bigint of any size whose magnitude is `words`, least
/// significant word first, negated if `negative`: the spelling of a literal
/// outside `i64`, which [`bigint_any`] cannot take. A zero magnitude is `0n`
/// whatever the sign, and leading zero words are dropped.
pub fn bigint_any_words<A: IVm>(negative: bool, words: &[u64]) -> Any<A> {
    let sign = if negative {
        Sign::Negative
    } else {
        Sign::Positive
    };
    BigInt::normalize_new(sign, words.iter().copied()).to_any()
}

/// An `Any` holding the number whose IEEE 754 bits are `v` — the one
/// spelling `fjs/media/rust` gives every number, so a generated module holds
/// the double a JavaScript engine held, bit for bit, `-0` included, except a
/// `NaN`: the language has one, so every `NaN` arrives as the quiet,
/// empty-payload one, whatever sign or payload the engine held it with.
pub fn f64_any<A: IVm>(v: u64) -> Any<A> {
    Number::from(f64::from_bits(v)).to_any()
}

/// A static function read from the runtime value by its id, `Object.is`:
/// what a compiled module's read of a static spells,
/// `static_read(&runtime, "Object.is")?` — the value's `static` function,
/// called with the id — the one closure the runtime holds for it, so two
/// reads are one function, as `Object.is === Object.is` is in JavaScript.
/// An id the runtime answers no function for is refused
/// ([`error::no_static_function`]): the parser admitted the id, so the
/// runtime's table is incomplete, and `undefined` would be a plausible
/// wrong answer. A throw of `static` itself is the read's.
pub fn static_read<A: IVm>(runtime: &Any<A>, path: &str) -> Result<Any<A>, Any<A>> {
    let read = runtime.clone().dot(string_any("static")).end()?;
    let value = read.call([string_any(path)].to_array().to_any())?;
    match Function::try_from(value) {
        Ok(f) => Ok(f.to_any()),
        Err(_) => Err(error::no_static_function(path)),
    }
}

/// `===` as an operator result. `==` on `Any` is exactly JavaScript's `===`,
/// but it yields a `bool` and so pins neither operand's `A`; this gives both
/// the same one and lifts the answer into the `Result` every other operator
/// returns, so a printed `===` is a statement like any other operator's.
pub fn strict_eq<A: IVm>(a: Any<A>, b: Any<A>) -> Result<Any<A>, Any<A>> {
    Ok((a == b).to_any())
}

/// `!==`, the negation of [`strict_eq`], for the same reason.
pub fn strict_ne<A: IVm>(a: Any<A>, b: Any<A>) -> Result<Any<A>, Any<A>> {
    Ok((a != b).to_any())
}

/// One item of an array literal or a call's argument list, as
/// [`spread_array`] and [`spread_call`] read it: a value, or an established
/// spread iterator ([`Any::get_iterator`]).
pub enum ArrayItem<A: IVm> {
    Value(Any<A>),
    Spread(IteratorRecord<A>),
}

/// An item that is its own value, `a` in `[a, ...b]`.
pub fn value_item<A: IVm>(v: Any<A>) -> ArrayItem<A> {
    ArrayItem::Value(v)
}

/// A spread item, `...b` in `[a, ...b]`. Take its iterator before the next
/// operand is evaluated: generated item lists propagate this `Result` with
/// `?` at the item's position. Iteration itself cannot throw or run represented
/// code for the VM's immutable arrays and strings ([`IteratorRecord`]).
pub fn spread_item<A: IVm>(v: Any<A>) -> Result<ArrayItem<A>, Any<A>> {
    v.get_iterator().map(ArrayItem::Spread)
}

/// Room for `additional` more elements, or the `RangeError` an array that
/// cannot be backed is: an allocation the machine refuses is a failure the
/// program can observe, not an abort of the process.
fn reserve<A: IVm>(values: &mut Vec<Any<A>>, additional: usize) -> Result<(), Any<A>> {
    values
        .try_reserve(additional)
        .map_err(|_| error::array_too_long())
}

/// The array an item list holds, a spread among them: each value an
/// element, and each spread every value its operand iterates, in order. A
/// spread of a value that is not iterable throws, so the array is an
/// operation's `Result` where an array without a spread is a value.
///
/// Every spread's iterator is already established by [`spread_item`], and the
/// array's length is bounded before anything is built: past JavaScript's limit,
/// `2³² − 1` elements and `Array<A>`'s `u32` length, the result is the `RangeError`
/// `ArrayCreate` throws, refused on the iterators' lower bounds — exact for
/// an array — and, since a string's code points are only known by walking
/// it, checked again as each element is added, so the build never passes
/// the limit. Delaying the iteration is unobservable: neither an array nor a
/// string runs code or throws while iterated. The elements' room is reserved up
/// front and before every growth, so a length under the limit whose elements
/// the machine cannot hold is the same `RangeError`, not an abort. The array
/// built from them is the container constructor's own allocation, which is
/// not fallible yet (`todo/131-non-panicking-allocator.md`): a machine that
/// can hold the elements but not a second copy of them still aborts.
pub fn spread_array<A: IVm>(
    items: impl IntoIterator<Item = ArrayItem<A>>,
) -> Result<Any<A>, Any<A>> {
    let parts: Vec<_> = items.into_iter().collect();
    let at_least: u64 = parts
        .iter()
        .map(|p| match p {
            ArrayItem::Value(_) => 1,
            ArrayItem::Spread(i) => i.size_hint().0 as u64,
        })
        .sum();
    let limit = u64::from(u32::MAX);
    if at_least > limit {
        return Err(error::array_too_long());
    }
    let mut values = Vec::new();
    reserve(&mut values, at_least as usize)?;
    let mut push = |v: Any<A>| -> Result<(), Any<A>> {
        if values.len() as u64 == limit {
            return Err(error::array_too_long());
        }
        reserve(&mut values, 1)?;
        values.push(v);
        Ok(())
    };
    for part in parts {
        match part {
            ArrayItem::Value(v) => push(v)?,
            ArrayItem::Spread(i) => i.into_iter().try_for_each(&mut push)?,
        }
    }
    Ok(values.to_array().to_any())
}

/// `f(...)` over an argument list holding a spread: the arguments
/// [`spread_array`] builds, then the call, so a spread's throw comes first,
/// as JavaScript evaluates the arguments before it calls.
pub fn spread_call<A: IVm>(
    f: Any<A>,
    items: impl IntoIterator<Item = ArrayItem<A>>,
) -> Result<Any<A>, Any<A>> {
    f.call(spread_array(items)?)
}

/// One entry of an object literal, as [`spread_object`] reads it: a
/// property, a key and its value, or a spread whose entries the value
/// gives ([`Any::object_spread`]).
pub enum ObjectItem<A: IVm> {
    Property(String<A>, Any<A>),
    Spread(Any<A>),
}

/// A property entry, `k: v` in `{k: v, ...o}`. A computed key uses
/// `property_item(key.to_string()?, value)`, establishing its string conversion
/// before the value argument is evaluated. The VM has no symbols, so
/// [`Any::to_string`] supplies `ToPropertyKey` for its values.
/// A plain object becomes `"[object Object]"`; an own callable `toString`
/// supplies the primitive, with `valueOf` as the fallback if needed. A throw or
/// failure to produce a primitive propagates before the value starts.
pub fn property_item<A: IVm>(k: String<A>, v: Any<A>) -> ObjectItem<A> {
    ObjectItem::Property(k, v)
}

/// A spread entry, `...o` in `{k: v, ...o}`.
pub fn spread_entries<A: IVm>(v: Any<A>) -> ObjectItem<A> {
    ObjectItem::Spread(v)
}

/// The object an entry list holds, a spread among them: each property and
/// each spread's entries appended in order to the raw property list, so a
/// later key overwrites an earlier one's value and keeps its position, as
/// JavaScript's does, through the view every reader takes
/// ([`Object::own_entries`](crate::vm::Object::own_entries)). An object
/// spread never throws, so this is a value, not a `Result`.
pub fn spread_object<A: IVm>(items: impl IntoIterator<Item = ObjectItem<A>>) -> Any<A> {
    let mut entries = Vec::new();
    for item in items {
        match item {
            ObjectItem::Property(k, v) => entries.push((k, v)),
            ObjectItem::Spread(v) => entries.extend(v.object_spread()),
        }
    }
    entries.to_object().to_any()
}

#[cfg(test)]
mod test {
    use super::*;
    use crate::{
        common::sized_index::SizedIndex,
        naive::Naive,
        vm::{Array, IVm, Object, Unpacked},
    };

    #[test]
    fn strings() {
        let direct: Any<Naive> = "a".into();
        assert_eq!(string_any::<Naive>("a"), direct);
        let key: String<Naive> = "a".into();
        assert_eq!(string_key::<Naive>("a"), key);
    }

    #[test]
    fn bigints() {
        assert_eq!(
            bigint_any::<Naive>(-1),
            Into::<BigInt<Naive>>::into(-1i64).to_any()
        );
    }

    #[test]
    fn bigints_of_any_size() {
        let word = |negative, words: &[u64]| bigint_any_words::<Naive>(negative, words);
        // Within `i64` it agrees with `bigint_any`, `i64::MIN` included.
        assert_eq!(word(false, &[1]), bigint_any(1));
        assert_eq!(word(true, &[1 << 63]), bigint_any(i64::MIN));
        assert_eq!(word(false, &[i64::MAX as u64]), bigint_any(i64::MAX));
        // Zero is `0n`, signed or padded.
        assert_eq!(word(true, &[]), bigint_any(0));
        assert_eq!(word(true, &[0, 0]), bigint_any(0));
        // A word boundary: `2n ** 64n`, and its negation.
        let two_64 = word(false, &[0, 1]);
        assert_eq!(two_64, (bigint_any::<Naive>(1) << bigint_any(64)).unwrap());
        assert_eq!(word(true, &[0, 1, 0]), (-two_64.clone()).unwrap());
        assert_ne!(two_64, word(false, &[1, 1]));
        // Several words, as the decimal `123456789012345678901234567890n`.
        let big = word(false, &[0xC373_E0EE_4E3F_0AD2, 0x1_8EE9_0FF6]);
        assert_eq!(
            big.to_string().unwrap(),
            "123456789012345678901234567890".into()
        );
    }

    #[test]
    fn numbers_as_text() {
        assert_eq!(number_text(f64::NAN), "NaN");
        assert_eq!(number_text(-0.0), "0");
        assert_eq!(number_text(-1.5), "-1.5");
        assert_eq!(number_text(1e21), "1e+21");
        assert_eq!(number_text(1e-7), "1e-7");
        // A tie between two candidates of one length goes to the even digit.
        assert_eq!(
            number_text(0x6_b5a4_ff2c_1a40_u64 as f64 + 0.25),
            "1888570120608320.2"
        );
    }

    #[test]
    fn numbers_by_their_bits() {
        let bits = |v: Any<Naive>| match v.into() {
            Unpacked::Number(x) => f64::from(x).to_bits(),
            _ => panic!("a number"),
        };
        assert_eq!(bits(f64_any(0x4002_6666_6666_6666)), 2.3f64.to_bits());
        assert_eq!(bits(f64_any(0x8000_0000_0000_0000)), (-0f64).to_bits());
        assert_eq!(bits(f64_any(0x7ff8_0000_0000_0000)), 0x7ff8_0000_0000_0000);
    }

    /// The two answer each other's negation, `NaN` against itself included:
    /// `NaN === NaN` is `false` and `NaN !== NaN` is `true`, as in JavaScript.
    #[test]
    fn strict_equality() {
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let nan = || f64_any::<Naive>(0x7ff8_0000_0000_0000);
        assert_eq!(strict_eq(one(), one()), Ok(true.to_any()));
        assert_eq!(strict_ne(one(), one()), Ok(false.to_any()));
        assert_eq!(strict_eq(nan(), nan()), Ok(false.to_any()));
        assert_eq!(strict_ne(nan(), nan()), Ok(true.to_any()));
        assert_eq!(strict_eq(one(), string_any("1")), Ok(false.to_any()));
    }

    /// The elements of an array result, compared by value: `==` on two
    /// arrays is `===`, identity.
    fn elements(r: Result<Any<Naive>, Any<Naive>>) -> Vec<Any<Naive>> {
        Array::try_from(r.unwrap()).unwrap().into_iter().collect()
    }

    /// `[1, ...'ab', ...[2]]` is `[1, 'a', 'b', 2]`, an empty spread adds
    /// nothing, and a spread of what is not iterable throws.
    #[test]
    fn spread_arrays() {
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let two = || f64_any::<Naive>(0x4000_0000_0000_0000);
        let inner: Any<Naive> = [two()].to_array().to_any();
        assert_eq!(
            elements(spread_array([
                value_item(one()),
                spread_item(string_any("ab")).unwrap(),
                spread_item(inner).unwrap(),
            ])),
            [one(), string_any("a"), string_any("b"), two()]
        );
        let empty: Any<Naive> = [].to_array().to_any();
        assert!(
            elements(spread_array([
                spread_item(string_any("")).unwrap(),
                spread_item(empty).unwrap()
            ]))
            .is_empty()
        );
        assert!(spread_item(one()).is_err());
    }

    /// Generated lists propagate each spread's admission before evaluating
    /// the next operand, even when that operand would fail differently.
    #[test]
    fn spread_admission_precedes_later_operands() {
        use crate::vm::Nullish;
        use core::cell::Cell;

        let reached = Cell::new(false);
        let later = || -> Result<Any<Naive>, Any<Naive>> {
            reached.set(true);
            Err(string_any("later"))
        };
        let result: Result<Any<Naive>, Any<Naive>> =
            (|| spread_array([spread_item(Nullish::Null.to_any())?, value_item(later()?)]))();
        assert_eq!(result.err(), Some(error::not_iterable()));
        assert!(!reached.get());
    }

    /// Past `2³² − 1` elements the result is the `RangeError`, refused on
    /// the iterators' exact lengths before anything is allocated: 65,537
    /// spreads of one 65,536-element array would be 2³² + 2¹⁶ elements.
    #[test]
    fn spread_array_too_long() {
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let block: Any<Naive> = (0..65_536)
            .map(|_| one())
            .collect::<Vec<_>>()
            .to_array()
            .to_any();
        let too_many = (0..65_537).map(|_| spread_item(block.clone()).unwrap());
        assert_eq!(spread_array(too_many).err(), Some(error::array_too_long()));
        let within = (0..2).map(|_| spread_item(block.clone()).unwrap());
        assert_eq!(elements(spread_array(within)).len(), 131_072);
    }

    /// A length under the limit whose elements the machine cannot hold is
    /// the `RangeError` too, not an abort: 65,535 spreads of one 65,537-element
    /// array are exactly `2³² − 1` elements. Skipped where the machine can
    /// reserve that room, as building it would take the machine's memory.
    #[test]
    fn spread_array_unbacked() {
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let block: Any<Naive> = (0..65_537)
            .map(|_| one())
            .collect::<Vec<_>>()
            .to_array()
            .to_any();
        let all = u32::MAX as usize;
        if Vec::<Any<Naive>>::new().try_reserve(all).is_ok() {
            return;
        }
        let spreads = (0..65_535).map(|_| spread_item(block.clone()).unwrap());
        assert_eq!(spread_array(spreads).err(), Some(error::array_too_long()));
    }

    /// `reserve` is the one place a refused reservation becomes the
    /// `RangeError`, and `usize::MAX` elements overflow the capacity of every
    /// `Vec` on every platform, so this holds where `spread_array_unbacked`
    /// skips itself. It does not show that `spread_array` calls it: that
    /// takes an allocator that refuses a real request.
    #[test]
    fn reserve_refuses_what_no_vec_can_hold() {
        let mut values: Vec<Any<Naive>> = Vec::new();
        assert_eq!(
            reserve(&mut values, usize::MAX),
            Err(error::array_too_long())
        );
        assert!(values.is_empty());
        assert_eq!(reserve(&mut values, 3), Ok(()));
        assert!(values.capacity() >= 3);
    }

    /// The callee receives the spread values as its arguments, and a spread
    /// that throws throws before the call, a callee that is not a function
    /// included.
    #[test]
    fn spread_calls() {
        use crate::vm::IVm;
        let identity: Any<Naive> =
            Naive::static_function(|_, args| Ok(args.to_any()), 0, [].to_array(), None).to_any();
        assert_eq!(
            elements(spread_call(
                identity,
                [spread_item(string_any("ab")).unwrap()]
            )),
            [string_any("a"), string_any("b")]
        );
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let bad_spread = (|| spread_call(one(), [spread_item(one())?]))();
        assert_eq!(bad_spread.err(), Some(error::not_iterable()));
        assert!(spread_call(one(), [spread_item(string_any("ab")).unwrap()]).is_err());
    }

    /// `{a: 1, ...{b: 2, a: 3}, ...'x'}` is `{0: 'x', a: 3, b: 2}`: the
    /// spread's `a` overwrites the first one's value and keeps its
    /// position, and the index key comes first; `{...null}` adds nothing.
    #[test]
    fn spread_objects() {
        use crate::vm::{Nullish, Object, ToObject};
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let two = || f64_any::<Naive>(0x4000_0000_0000_0000);
        let three = || f64_any::<Naive>(0x4008_0000_0000_0000);
        let inner: Any<Naive> = [(string_key("b"), two()), (string_key("a"), three())]
            .to_object()
            .to_any();
        let result = spread_object([
            property_item(string_key("a"), one()),
            spread_entries(inner),
            spread_entries(string_any("x")),
            spread_entries(Nullish::Null.to_any()),
        ]);
        let entries = Object::try_from(result).unwrap().own_entries();
        assert_eq!(
            entries,
            [
                (string_key("0"), string_any("x")),
                (string_key("a"), three()),
                (string_key("b"), two()),
            ]
        );
    }

    /// A computed key is its `ToString`, as an own key: a number is its
    /// text and `-0` is `"0"`; a key that cannot be converted throws before
    /// the entry exists.
    #[test]
    fn computed_keys() {
        let one = || f64_any::<Naive>(0x3ff0_0000_0000_0000);
        let negative_zero = || f64_any::<Naive>(0x8000_0000_0000_0000);
        let object = spread_object([
            property_item(one().to_string().unwrap(), string_any("a")),
            property_item(negative_zero().to_string().unwrap(), string_any("b")),
            property_item(Any::undefined().to_string().unwrap(), string_any("c")),
            property_item(string_any("1").to_string().unwrap(), string_any("d")),
        ]);
        let entries = Object::try_from(object).unwrap().own_entries();
        assert_eq!(
            entries,
            [
                (string_key("0"), string_any("b")),
                (string_key("1"), string_any("d")),
                (string_key("undefined"), string_any("c")),
            ]
        );
        let plain = Object::<Naive>::default().to_any();
        let item = property_item(plain.to_string().unwrap(), one());
        let ObjectItem::Property(key, _) = item else {
            panic!()
        };
        assert_eq!(key, string_key("[object Object]"));
    }

    /// An own conversion method supplies the key, and its errors propagate.
    #[test]
    fn computed_key_conversion() {
        use core::cell::Cell;

        let with_to_string = |method: Any<Naive>| -> Any<Naive> {
            [(string_key("toString"), method)].to_object().to_any()
        };
        let method =
            Naive::static_function(|_, _| Ok(string_any("own")), 0, [].to_array(), None).to_any();
        let item = property_item(
            with_to_string(method).to_string().unwrap(),
            string_any("value"),
        );
        let object = Object::try_from(spread_object([item])).unwrap();
        assert_eq!(
            object.own_entries(),
            [(string_key("own"), string_any("value"))]
        );

        let method = Naive::static_function(
            |_, _| Err(string_any("key conversion failed")),
            0,
            [].to_array(),
            None,
        )
        .to_any();
        let reached = Cell::new(false);
        let later = || -> Result<Any<Naive>, Any<Naive>> {
            reached.set(true);
            Err(string_any("value failed"))
        };
        let item = (|| -> Result<ObjectItem<Naive>, Any<Naive>> {
            Ok(property_item(with_to_string(method).to_string()?, later()?))
        })();
        assert!(matches!(
            item,
            Err(error) if error == string_any("key conversion failed")
        ));
        assert!(!reached.get());
        assert!(with_to_string(f64_any(0)).to_string().is_err());

        let item = (|| -> Result<ObjectItem<Naive>, Any<Naive>> {
            Ok(property_item(string_any("own").to_string()?, later()?))
        })();
        assert!(matches!(item, Err(error) if error == string_any("value failed")));
        assert!(reached.get());
    }

    /// A string of code units holds what no `&str` can, a lone surrogate,
    /// and agrees with the `&str` spelling where both exist.
    #[test]
    fn strings_of_code_units() {
        let lone = string_key_utf16::<Naive>(&[0x61, 0xd800]);
        assert_eq!(lone.length(), 2);
        assert_eq!(lone[1], 0xd800);
        assert_eq!(string_any_utf16::<Naive>(&[0x61, 0x62]), string_any("ab"));
        assert_eq!(string_key_utf16::<Naive>(&[]), string_key(""));
    }
}