@tishlang/tish 1.13.1 → 2.0.0

package/crates/tish_core/src/value.rs

@@ -4,6 +4,8 @@ use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 
 use ahash::AHashMap;
+use indexmap::IndexMap;
+use smallvec::SmallVec;
 
 use crate::vmref::VmRef;
 
@@ -63,10 +65,63 @@ use fancy_regex::Regex;
 /// `Rc<dyn Fn>` for zero-overhead single-threaded execution (wasm / wasi /
 /// interpreter / cranelift / llvm VMs and any Rust native build without
 /// `http`).
+/// A callable value's behaviour. Replaces the former `Arc<dyn Fn(&[Value]) -> Value>`:
+/// the trait lets a *bytecode-VM* closure additionally expose its compiled chunk (via the
+/// `as_any` downcast), so the VM's `Call` opcode can run tish→tish calls on an explicit
+/// frame stack (task #39, the frame-VM) instead of recursively re-entering `run_chunk` —
+/// while native builtins use the blanket [`FnCallable`] adapter and keep plain `Fn`
+/// behaviour. `Send + Sync` is conditional on `send-values`, exactly like `NativeFn` was.
 #[cfg(feature = "send-values")]
-pub type NativeFn = Arc<dyn Fn(&[Value]) -> Value + Send + Sync>;
+pub trait Callable: Send + Sync {
+    fn call(&self, args: &[Value]) -> Value;
+    /// Downcast hook for the VM frame path; native adapters return themselves (downcast fails).
+    fn as_any(&self) -> &dyn std::any::Any;
+}
+#[cfg(not(feature = "send-values"))]
+pub trait Callable {
+    fn call(&self, args: &[Value]) -> Value;
+    fn as_any(&self) -> &dyn std::any::Any;
+}
+
+/// Adapter wrapping a plain `Fn` closure (every native builtin) as a [`Callable`].
+pub struct FnCallable<F>(pub F);
+#[cfg(feature = "send-values")]
+impl<F: Fn(&[Value]) -> Value + Send + Sync + 'static> Callable for FnCallable<F> {
+    #[inline]
+    fn call(&self, args: &[Value]) -> Value {
+        (self.0)(args)
+    }
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+}
+#[cfg(not(feature = "send-values"))]
+impl<F: Fn(&[Value]) -> Value + 'static> Callable for FnCallable<F> {
+    #[inline]
+    fn call(&self, args: &[Value]) -> Value {
+        (self.0)(args)
+    }
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+}
+
+#[cfg(feature = "send-values")]
+pub type NativeFn = Arc<dyn Callable>;
 #[cfg(not(feature = "send-values"))]
-pub type NativeFn = std::rc::Rc<dyn Fn(&[Value]) -> Value>;
+pub type NativeFn = std::rc::Rc<dyn Callable>;
+
+/// Build a raw [`NativeFn`] from a plain closure (wraps it in [`FnCallable`]). For sites that
+/// need a `NativeFn` handle directly rather than a `Value::Function` (e.g. HTTP/promise/timer
+/// internals that store the callable). The `Value::Function` variant is built via [`Value::native`].
+#[cfg(feature = "send-values")]
+pub fn native_fn<F: Fn(&[Value]) -> Value + Send + Sync + 'static>(f: F) -> NativeFn {
+    Arc::new(FnCallable(f))
+}
+#[cfg(not(feature = "send-values"))]
+pub fn native_fn<F: Fn(&[Value]) -> Value + 'static>(f: F) -> NativeFn {
+    std::rc::Rc::new(FnCallable(f))
+}
 
 /// Trait for opaque Rust types exposed to Tish (e.g. Polars DataFrame).
 /// Implementors provide method dispatch so Tish can call methods on the value.
@@ -106,6 +161,17 @@ pub trait TishOpaque {
 /// Implemented by the runtime for native compile; interpreter uses its own Promise.
 pub trait TishPromise: Send + Sync {
     fn block_until_settled(&self) -> std::result::Result<Value, Value>;
+    /// Try to settle WITHOUT blocking. Returns `Some(result)` if the promise was already
+    /// settled before this call; returns `None` if it is still pending (a background thread
+    /// / I/O task has not completed yet). Default: always pending — implementors of async
+    /// promises (fetch, spawn) leave this as `None`; `ImmediateSettledPromise` overrides it.
+    ///
+    /// Used by `race`/`any`/`allSettled` to handle already-settled promises in input-order
+    /// (deterministic, JS-compatible) before falling back to concurrent thread waiting for
+    /// genuinely-pending ones.
+    fn try_settle(&self) -> Option<std::result::Result<Value, Value>> {
+        None
+    }
 }
 
 /// JavaScript RegExp flags
@@ -278,13 +344,20 @@ impl TishRegExp {
 /// **Thread safety**: `Value: Send + Sync`. Mutable payloads live inside
 /// [`VmRef`], a `Send + Sync` `Arc<Mutex<T>>` wrapper that preserves the
 /// `RefCell`-style borrow API. Functions are `Arc<dyn Fn + Send + Sync>`.
-#[derive(Clone)]
+#[derive(Clone, Default)]
 pub enum Value {
     Number(f64),
-    String(Arc<str>),
+    String(arcstr::ArcStr),
     Bool(bool),
+    #[default]
     Null,
     Array(VmRef<Vec<Value>>),
+    /// Packed f64 array — `TISH_PACKED_ARRAYS` mode only. All elements are f64; a non-numeric
+    /// push/set/op materializes to `Value::Array` first. Eliminates per-element boxing and
+    /// enables direct `sort_unstable_by` without an unbox pass. Created by all-numeric array
+    /// literals, `new Array(n)` (zero-filled), and from numeric HOF results. Never created
+    /// when `packed_arrays_enabled()` is false — callers check before constructing.
+    NumberArray(VmRef<Vec<f64>>),
     Object(VmRef<ObjectData>),
     /// ECMAScript-style primitive symbol (identity by `Arc`).
     Symbol(Arc<TishSymbol>),
@@ -297,18 +370,335 @@ pub enum Value {
     Opaque(Arc<dyn TishOpaque>),
 }
 
+// Size guard. `Value` is 24 bytes: `String` is thin (`ArcStr`, 8B), but `Function`/`Promise`/`Opaque`
+// are fat `Arc<dyn …>` (data+vtable, 16B) ⇒ 16B payload + discriminant = 24.
+//
+// NOTE — shrinking to 16B was tried and REVERTED (see docs/perf.md "Value-shrink"): thinning the
+// three `Arc<dyn>` variants to `Arc<Box<dyn>>` (8B) DID make `Value` 16B and stayed green on all 6
+// backends, but it REGRESSED numeric dispatch ~8–10% (measured A/B interleaved, both in- AND
+// out-of-cache). tish is dispatch-bound, NOT memory-bandwidth-bound on `Value` size; the
+// boxing/enum-layout change pessimized the hot `Number` path. Smaller `Value` ≠ faster here. Do not
+// re-attempt the box trick; only a dispatch-level change (e.g. NaN-box's branch-free tag test, not
+// its size) could pay off. Gated to 64-bit: wasm32 (wasi) has 32-bit pointers, so size differs there.
+#[cfg(target_pointer_width = "64")]
+const _: () = assert!(std::mem::size_of::<Value>() == 24);
+
+/// Number of properties kept inline (no heap hashmap) before promoting to a map.
+const PROPMAP_INLINE: usize = 8;
+
+/// String-keyed property storage for objects.
+///
+/// Small objects (the overwhelming common case — `{ id, name, active }`) keep
+/// their entries inline with linear-scan lookup: no separate hashmap allocation
+/// and good cache locality, which beats hashing for a handful of keys. Objects
+/// that grow past [`PROPMAP_INLINE`] keys promote to an insertion-ordered
+/// `IndexMap` so large objects (e.g. `JSON.parse` output) keep O(1) lookup and
+/// never hit O(n²). Iteration is always **insertion order**, matching JS/Node.
+///
+/// Exposes the `AHashMap`-compatible surface (`get`/`insert`/`iter`/…) the rest
+/// of the runtime already uses, so it is a drop-in for the old `ObjectMap` field.
+#[derive(Clone, Debug, Default)]
+pub struct PropMap {
+    inline: SmallVec<[(Arc<str>, Value); PROPMAP_INLINE]>,
+    map: Option<Box<IndexMap<Arc<str>, Value, ahash::RandomState>>>,
+    /// Hidden-class identity for this object's ordered key-set (JSC Structure). `EMPTY_SHAPE` (0)
+    /// for `{}`. Maintained by `insert` (new key → `shape::transition`) and reset to `DICT_SHAPE` by
+    /// `remove`. Lets the VM's inline caches compare a `u32` instead of hashing a key. INVARIANT: a
+    /// non-empty PropMap never has `EMPTY_SHAPE` (every key-add transitions away from it) — the IC
+    /// relies on this, so all key-adds must go through `insert` (the only mutation path; fields private).
+    shape: crate::shape::ShapeId,
+}
+
+impl PropMap {
+    #[inline]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_capacity(n: usize) -> Self {
+        if n > PROPMAP_INLINE {
+            Self {
+                inline: SmallVec::new(),
+                map: Some(Box::new(IndexMap::with_capacity_and_hasher(
+                    n,
+                    ahash::RandomState::default(),
+                ))),
+                shape: crate::shape::EMPTY_SHAPE,
+            }
+        } else {
+            Self::default()
+        }
+    }
+
+    /// The hidden-class id for this object's current key-set (for the VM's inline caches).
+    #[inline]
+    pub fn shape(&self) -> crate::shape::ShapeId {
+        self.shape
+    }
+
+    /// Value at slot `i` (insertion order). For the inline-cache hit path: once a `(shape, index)`
+    /// is cached, a shape match means the property is at this stable index.
+    #[inline]
+    pub fn value_at_index(&self, i: usize) -> Option<&Value> {
+        match &self.map {
+            Some(m) => m.get_index(i).map(|(_, v)| v),
+            None => self.inline.get(i).map(|(_, v)| v),
+        }
+    }
+
+    /// Mutable value at slot `i` (insertion order) — for the SetMember inline-cache update path.
+    #[inline]
+    pub fn value_at_index_mut(&mut self, i: usize) -> Option<&mut Value> {
+        match &mut self.map {
+            Some(m) => m.get_index_mut(i).map(|(_, v)| v),
+            None => self.inline.get_mut(i).map(|(_, v)| v),
+        }
+    }
+
+    /// Like `get`, but also returns the property's slot index — used to *fill* an inline cache on a miss.
+    #[inline]
+    pub fn get_with_index(&self, key: &str) -> Option<(&Value, usize)> {
+        match &self.map {
+            Some(m) => m.get_full(key).map(|(i, _, v)| (v, i)),
+            None => self
+                .inline
+                .iter()
+                .position(|(k, _)| k.as_ref() == key)
+                .map(|i| (&self.inline[i].1, i)),
+        }
+    }
+
+    #[inline]
+    pub fn len(&self) -> usize {
+        match &self.map {
+            Some(m) => m.len(),
+            None => self.inline.len(),
+        }
+    }
+
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    #[inline]
+    pub fn get(&self, key: &str) -> Option<&Value> {
+        match &self.map {
+            Some(m) => m.get(key),
+            None => self
+                .inline
+                .iter()
+                .find(|(k, _)| k.as_ref() == key)
+                .map(|(_, v)| v),
+        }
+    }
+
+    #[inline]
+    pub fn get_mut(&mut self, key: &str) -> Option<&mut Value> {
+        match &mut self.map {
+            Some(m) => m.get_mut(key),
+            None => self
+                .inline
+                .iter_mut()
+                .find(|(k, _)| k.as_ref() == key)
+                .map(|(_, v)| v),
+        }
+    }
+
+    #[inline]
+    pub fn contains_key(&self, key: &str) -> bool {
+        self.get(key).is_some()
+    }
+
+    pub fn insert(&mut self, key: Arc<str>, val: Value) -> Option<Value> {
+        if let Some(m) = &mut self.map {
+            // Map path (>PROPMAP_INLINE keys). A new key transitions the shape; an update doesn't.
+            let kc = Arc::clone(&key);
+            let prev = m.insert(key, val);
+            if prev.is_none() {
+                self.shape = crate::shape::transition(self.shape, &kc);
+            }
+            return prev;
+        }
+        if let Some(slot) = self.inline.iter_mut().find(|(k, _)| k.as_ref() == key.as_ref()) {
+            // Update existing key → value changes, layout (shape) does not.
+            return Some(std::mem::replace(&mut slot.1, val));
+        }
+        // New key (inline storage) → transition the shape away from the current one.
+        self.shape = crate::shape::transition(self.shape, &key);
+        if self.inline.len() >= PROPMAP_INLINE {
+            // Promote inline storage to an insertion-ordered map (keys + their order are preserved,
+            // so the shape stays valid).
+            let mut m: IndexMap<Arc<str>, Value, ahash::RandomState> =
+                IndexMap::with_capacity_and_hasher(self.inline.len() + 1, ahash::RandomState::default());
+            for (k, v) in self.inline.drain(..) {
+                m.insert(k, v);
+            }
+            m.insert(key, val);
+            self.map = Some(Box::new(m));
+            return None;
+        }
+        self.inline.push((key, val));
+        None
+    }
+
+    pub fn remove(&mut self, key: &str) -> Option<Value> {
+        let removed = match &mut self.map {
+            // shift_remove preserves insertion order (vs swap_remove).
+            Some(m) => m.shift_remove(key),
+            None => self
+                .inline
+                .iter()
+                .position(|(k, _)| k.as_ref() == key)
+                .map(|pos| self.inline.remove(pos).1),
+        };
+        if removed.is_some() {
+            // Deleting shifts slot indices → this object opts out of shape-based inline caches.
+            self.shape = crate::shape::DICT_SHAPE;
+        }
+        removed
+    }
+
+    // Iterators return concrete enum types (not `Box<dyn>`) so iteration never
+    // heap-allocates — critical for the per-request JSON stringify hot path
+    // (`json.rs` iterates `strings.keys()` on every response object).
+    #[inline]
+    pub fn iter(&self) -> PropMapIter<'_> {
+        match &self.map {
+            Some(m) => PropMapIter::Map(m.iter()),
+            None => PropMapIter::Inline(self.inline.iter()),
+        }
+    }
+
+    #[inline]
+    pub fn keys(&self) -> PropMapKeys<'_> {
+        match &self.map {
+            Some(m) => PropMapKeys::Map(m.keys()),
+            None => PropMapKeys::Inline(self.inline.iter()),
+        }
+    }
+
+    #[inline]
+    pub fn values(&self) -> PropMapValues<'_> {
+        match &self.map {
+            Some(m) => PropMapValues::Map(m.values()),
+            None => PropMapValues::Inline(self.inline.iter()),
+        }
+    }
+
+    pub fn reserve(&mut self, additional: usize) {
+        if let Some(m) = &mut self.map {
+            m.reserve(additional);
+        }
+    }
+}
+
+impl FromIterator<(Arc<str>, Value)> for PropMap {
+    fn from_iter<I: IntoIterator<Item = (Arc<str>, Value)>>(iter: I) -> Self {
+        let mut pm = PropMap::default();
+        for (k, v) in iter {
+            pm.insert(k, v);
+        }
+        pm
+    }
+}
+
+impl Extend<(Arc<str>, Value)> for PropMap {
+    fn extend<I: IntoIterator<Item = (Arc<str>, Value)>>(&mut self, iter: I) {
+        for (k, v) in iter {
+            self.insert(k, v);
+        }
+    }
+}
+
+impl IntoIterator for PropMap {
+    type Item = (Arc<str>, Value);
+    type IntoIter = PropMapIntoIter;
+    fn into_iter(self) -> Self::IntoIter {
+        match self.map {
+            Some(m) => PropMapIntoIter::Map(m.into_iter()),
+            None => PropMapIntoIter::Inline(self.inline.into_iter()),
+        }
+    }
+}
+
+/// Zero-allocation borrowing iterator over [`PropMap`] entries (insertion order).
+pub enum PropMapIter<'a> {
+    Inline(std::slice::Iter<'a, (Arc<str>, Value)>),
+    Map(indexmap::map::Iter<'a, Arc<str>, Value>),
+}
+impl<'a> Iterator for PropMapIter<'a> {
+    type Item = (&'a Arc<str>, &'a Value);
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            PropMapIter::Inline(it) => it.next().map(|(k, v)| (k, v)),
+            PropMapIter::Map(it) => it.next(),
+        }
+    }
+}
+
+/// Zero-allocation key iterator over [`PropMap`] (insertion order).
+pub enum PropMapKeys<'a> {
+    Inline(std::slice::Iter<'a, (Arc<str>, Value)>),
+    Map(indexmap::map::Keys<'a, Arc<str>, Value>),
+}
+impl<'a> Iterator for PropMapKeys<'a> {
+    type Item = &'a Arc<str>;
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            PropMapKeys::Inline(it) => it.next().map(|(k, _)| k),
+            PropMapKeys::Map(it) => it.next(),
+        }
+    }
+}
+
+/// Zero-allocation value iterator over [`PropMap`] (insertion order).
+pub enum PropMapValues<'a> {
+    Inline(std::slice::Iter<'a, (Arc<str>, Value)>),
+    Map(indexmap::map::Values<'a, Arc<str>, Value>),
+}
+impl<'a> Iterator for PropMapValues<'a> {
+    type Item = &'a Value;
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            PropMapValues::Inline(it) => it.next().map(|(_, v)| v),
+            PropMapValues::Map(it) => it.next(),
+        }
+    }
+}
+
+/// Owning iterator over [`PropMap`] entries (insertion order).
+#[allow(clippy::large_enum_variant)] // `Inline` is intentionally unboxed to keep PropMap iteration allocation-free
+pub enum PropMapIntoIter {
+    Inline(smallvec::IntoIter<[(Arc<str>, Value); PROPMAP_INLINE]>),
+    Map(indexmap::map::IntoIter<Arc<str>, Value>),
+}
+impl Iterator for PropMapIntoIter {
+    type Item = (Arc<str>, Value);
+    #[inline]
+    fn next(&mut self) -> Option<Self::Item> {
+        match self {
+            PropMapIntoIter::Inline(it) => it.next(),
+            PropMapIntoIter::Map(it) => it.next(),
+        }
+    }
+}
+
 /// Ordinary object: string-keyed properties plus optional symbol-keyed side map.
 #[derive(Clone, Debug, Default)]
 pub struct ObjectData {
-    pub strings: ObjectMap,
+    pub strings: PropMap,
     pub symbols: Option<AHashMap<u64, Value>>,
 }
 
 impl ObjectData {
     #[inline]
-    pub fn from_strings(strings: ObjectMap) -> Self {
+    pub fn from_strings<I: IntoIterator<Item = (Arc<str>, Value)>>(strings: I) -> Self {
         Self {
-            strings,
+            strings: strings.into_iter().collect(),
             symbols: None,
         }
     }
@@ -355,7 +745,7 @@ pub fn object_set(obj: &Value, key: &Value, val: Value) -> Result<(), String> {
             Ok(())
         }
         Value::String(k) => {
-            b.strings.insert(Arc::clone(k), val);
+            b.strings.insert(Arc::from(k.as_str()), val);
             Ok(())
         }
         _ => Err(format!(
@@ -382,10 +772,72 @@ pub fn object_has(obj: &Value, key: &Value) -> bool {
     }
 }
 
+/// Drain a JS-style iterator object — one with a callable `next()` that returns
+/// `{ value, done }` — into a `Vec`, calling `next()` until `done` is truthy. Returns
+/// `None` when `obj` is not such an object (no callable `next`), so callers fall back
+/// to their array/string handling. This is what makes a `Map`/`Set` iterator (the result
+/// of `.values()`/`.keys()`/`.entries()`) usable in `for…of`, spread, and `Array.from`.
+/// A missing/absent `done` is treated as truthy so a malformed object can't spin forever;
+/// the native iterators always set `done`, so well-formed iteration is exact.
+pub fn drain_iterator(obj: &Value) -> Option<Vec<Value>> {
+    if !matches!(obj, Value::Object(_)) {
+        return None;
+    }
+    // Fast path: tish's own `Map`/`Set` iterators expose `__drain__`, which returns the remaining
+    // items as one array (respecting the current position) and exhausts the iterator — so `for…of`
+    // and spread don't pay the per-element `{ value, done }` allocation of the generic `next()` loop.
+    if let Some(Value::Function(drain)) = object_get(obj, &Value::String("__drain__".into())) {
+        if let Value::Array(arr) = drain.call(&[]) {
+            return Some(arr.borrow().clone());
+        }
+    }
+    let Value::Function(next) = object_get(obj, &Value::String("next".into()))? else {
+        return None;
+    };
+    let done_key = Value::String("done".into());
+    let value_key = Value::String("value".into());
+    let mut out = Vec::new();
+    loop {
+        let res = next.call(&[]);
+        let done = object_get(&res, &done_key)
+            .map(|v| v.is_truthy())
+            .unwrap_or(true);
+        if done {
+            break;
+        }
+        out.push(object_get(&res, &value_key).unwrap_or(Value::Null));
+    }
+    Some(out)
+}
+
+/// JS `ToInt32`: NaN and ±Infinity map to `0`; every other value is truncated toward zero and
+/// reduced modulo 2³². `f64 as i64` is exact for the finite `< 2⁶³` magnitudes real bitwise code
+/// produces (then `as i32` truncates the low 32 bits = the modulo); the `is_finite` guard is what
+/// makes `Infinity`/`-Infinity` correct — `f64 as i64` *saturates* (`+∞ → i64::MAX → -1`), which is
+/// NOT the JS result. One always-predicted branch, so the hot path (finite hash values) is unaffected.
+#[inline]
+pub fn to_int32(x: f64) -> i32 {
+    if x.is_finite() {
+        x as i64 as i32
+    } else {
+        0
+    }
+}
+
+/// JS `ToUint32`: as [`to_int32`] but reinterpreted unsigned (NaN/±Infinity → `0`).
+#[inline]
+pub fn to_uint32(x: f64) -> u32 {
+    if x.is_finite() {
+        x as i64 as u32
+    } else {
+        0
+    }
+}
+
 /// Invoke a callable [`Value`]: [`Value::Function`], or an object exposing `__call` (e.g. `Symbol`).
 pub fn value_call(callee: &Value, args: &[Value]) -> Value {
     match callee {
-        Value::Function(f) => f(args),
+        Value::Function(f) => f.call(args),
         Value::Object(o) => {
             let inner = o.borrow().strings.get("__call").cloned();
             if let Some(inner) = inner {
@@ -407,7 +859,7 @@ pub fn value_call(callee: &Value, args: &[Value]) -> Value {
 pub fn merge_object_data(left: &VmRef<ObjectData>, right: &VmRef<ObjectData>) -> ObjectData {
     let l = left.borrow();
     let r = right.borrow();
-    let mut strings = ObjectMap::with_capacity(l.strings.len() + r.strings.len());
+    let mut strings = PropMap::with_capacity(l.strings.len() + r.strings.len());
     strings.extend(l.strings.iter().map(|(k, v)| (Arc::clone(k), v.clone())));
     strings.extend(r.strings.iter().map(|(k, v)| (Arc::clone(k), v.clone())));
     let mut symbols: Option<AHashMap<u64, Value>> = None;
@@ -429,10 +881,11 @@ impl std::fmt::Debug for Value {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
             Value::Number(n) => write!(f, "Number({})", n),
-            Value::String(s) => write!(f, "String({:?})", s.as_ref()),
+            Value::String(s) => write!(f, "String({:?})", s.as_str()),
             Value::Bool(b) => write!(f, "Bool({})", b),
             Value::Null => write!(f, "Null"),
             Value::Array(arr) => write!(f, "Array({:?})", arr.borrow()),
+            Value::NumberArray(arr) => write!(f, "NumberArray({:?})", arr.borrow()),
             Value::Object(obj) => write!(f, "Object({:?})", obj.borrow()),
             Value::Symbol(s) => write!(f, "Symbol({})", s.id),
             Value::Function(_) => write!(f, "Function"),
@@ -449,21 +902,81 @@ impl std::fmt::Debug for Value {
     }
 }
 
+/// Format an `f64` exactly like JavaScript's `Number.prototype.toString` (radix 10) — the
+/// algorithm behind `console.log(n)` and `String(n)`. Rust's default `{}` never uses
+/// exponential form and so prints `6.022e23` as `602200000000000000000000`; JS switches to
+/// exponential when the decimal point lands past digit 21 or before digit −6.
+///
+/// We take the shortest round-tripping digits from Rust's `{:e}` (a Ryū/Grisu-class shortest
+/// formatter, matching V8's digit choice) and lay them out per the ECMAScript rule: plain
+/// decimal when the point position `n` is in `(-6, 21]`, otherwise `d[.ddd]e±E` with `E = n-1`
+/// (sign always shown, no leading zeros in the exponent). `-0` renders as `"-0"` (matching
+/// `console.log` and tish's existing behavior).
+pub fn js_number_to_string(value: f64) -> String {
+    if value.is_nan() {
+        return "NaN".to_string();
+    }
+    if value == f64::INFINITY {
+        return "Infinity".to_string();
+    }
+    if value == f64::NEG_INFINITY {
+        return "-Infinity".to_string();
+    }
+    if value == 0.0 {
+        return if value.is_sign_negative() { "-0" } else { "0" }.to_string();
+    }
+
+    let negative = value < 0.0;
+    // Shortest round-trip digits + base-10 exponent, e.g. "6.022e23" → ("6022", 23).
+    let sci = format!("{:e}", value.abs());
+    let (mantissa, exp_str) = sci
+        .split_once('e')
+        .expect("LowerExp formatting always contains 'e'");
+    let exp: i32 = exp_str
+        .parse()
+        .expect("LowerExp exponent is a valid integer");
+    let digits: String = mantissa.chars().filter(|&c| c != '.').collect();
+    let k = digits.len() as i32; // significant digit count (≤ 17 for an f64)
+    let point = exp + 1; // ECMAScript's `n`: value = digits × 10^(point − k)
+
+    let mut out = String::new();
+    if negative {
+        out.push('-');
+    }
+    if k <= point && point <= 21 {
+        // Integer, zero-padded: digits then (point − k) trailing zeros.
+        out.push_str(&digits);
+        out.push_str(&"0".repeat((point - k) as usize));
+    } else if 0 < point && point <= 21 {
+        // Decimal point inside the digit string.
+        out.push_str(&digits[..point as usize]);
+        out.push('.');
+        out.push_str(&digits[point as usize..]);
+    } else if -6 < point && point <= 0 {
+        // Leading-zero fraction: "0." then (−point) zeros then the digits.
+        out.push_str("0.");
+        out.push_str(&"0".repeat((-point) as usize));
+        out.push_str(&digits);
+    } else {
+        // Exponential: first digit, optional `.rest`, then `e±E`.
+        let e = point - 1;
+        out.push_str(&digits[..1]);
+        if k > 1 {
+            out.push('.');
+            out.push_str(&digits[1..]);
+        }
+        out.push('e');
+        out.push(if e >= 0 { '+' } else { '-' });
+        out.push_str(&e.abs().to_string());
+    }
+    out
+}
+
 impl Value {
     /// Convert value to display string (for console output).
     pub fn to_display_string(&self) -> String {
         match self {
-            Value::Number(n) => {
-                if n.is_nan() {
-                    "NaN".to_string()
-                } else if *n == f64::INFINITY {
-                    "Infinity".to_string()
-                } else if *n == f64::NEG_INFINITY {
-                    "-Infinity".to_string()
-                } else {
-                    n.to_string()
-                }
-            }
+            Value::Number(n) => js_number_to_string(*n),
             Value::String(s) => s.to_string(),
             Value::Bool(b) => b.to_string(),
             Value::Null => "null".to_string(),
@@ -472,6 +985,14 @@ impl Value {
                     arr.borrow().iter().map(|v| v.to_display_string()).collect();
                 format!("[{}]", inner.join(", "))
             }
+            Value::NumberArray(arr) => {
+                let inner: Vec<String> = arr
+                    .borrow()
+                    .iter()
+                    .map(|&n| if n.is_nan() { "null".to_string() } else { Value::Number(n).to_display_string() })
+                    .collect();
+                format!("[{}]", inner.join(", "))
+            }
             Value::Object(obj) => {
                 let inner: Vec<String> = obj
                     .borrow()
@@ -499,6 +1020,37 @@ impl Value {
         }
     }
 
+    /// JavaScript `ToString` coercion (the value's `.toString()`), as used by `Array.prototype.join`,
+    /// string concatenation, and template literals — distinct from [`Self::to_display_string`], which
+    /// is the *inspect/console* form (arrays bracketed, strings quoted in some contexts). The key
+    /// JS-conformance differences from display: a nested **array** stringifies to its own
+    /// comma-joined `toString` (recursively, always `,` regardless of the outer separator), an
+    /// **object** becomes `"[object Object]"`, and primitives render as their plain value. `null`
+    /// renders as `"null"` here (matching `String(null)`); `join` itself maps `null`/`undefined`
+    /// elements to `""` *before* calling this, per the spec.
+    pub fn to_js_string(&self) -> String {
+        match self {
+            Value::Array(arr) => arr
+                .borrow()
+                .iter()
+                .map(|v| match v {
+                    Value::Null => String::new(),
+                    other => other.to_js_string(),
+                })
+                .collect::<Vec<_>>()
+                .join(","),
+            Value::NumberArray(arr) => arr
+                .borrow()
+                .iter()
+                .map(|n| Value::Number(*n).to_js_string())
+                .collect::<Vec<_>>()
+                .join(","),
+            Value::Object(_) => "[object Object]".to_string(),
+            // Primitives (and the remaining cases) coincide with the display form.
+            _ => self.to_display_string(),
+        }
+    }
+
     /// Check if value is truthy (for conditionals).
     pub fn is_truthy(&self) -> bool {
         match self {
@@ -524,6 +1076,7 @@ impl Value {
             (Value::Bool(a), Value::Bool(b)) => a == b,
             (Value::Null, Value::Null) => true,
             (Value::Array(a), Value::Array(b)) => VmRef::ptr_eq(a, b),
+            (Value::NumberArray(a), Value::NumberArray(b)) => VmRef::ptr_eq(a, b),
             (Value::Object(a), Value::Object(b)) => VmRef::ptr_eq(a, b),
             #[cfg(feature = "send-values")]
             (Value::Function(a), Value::Function(b)) => Arc::ptr_eq(a, b),
@@ -549,7 +1102,7 @@ impl Value {
     where
         F: Fn(&[Value]) -> Value + Send + Sync + 'static,
     {
-        Value::Function(Arc::new(f))
+        Value::Function(Arc::new(FnCallable(f)))
     }
 
     #[cfg(not(feature = "send-values"))]
@@ -557,7 +1110,7 @@ impl Value {
     where
         F: Fn(&[Value]) -> Value + 'static,
     {
-        Value::Function(std::rc::Rc::new(f))
+        Value::Function(std::rc::Rc::new(FnCallable(f)))
     }
 
     /// Create a new array Value from a Vec.
@@ -570,11 +1123,66 @@ impl Value {
         Value::Object(VmRef::new(ObjectData::from_strings(map)))
     }
 
+    /// Create an object directly from key/value pairs, building the `PropMap`
+    /// in one pass with **no intermediate `AHashMap`**. Used by the Rust
+    /// backend's object-literal codegen and any hot path that knows its pairs,
+    /// so small objects (the common case) cost a single inline allocation.
+    pub fn object_from_pairs<const N: usize>(pairs: [(Arc<str>, Value); N]) -> Self {
+        let mut strings = PropMap::with_capacity(N);
+        for (k, v) in pairs {
+            strings.insert(k, v);
+        }
+        Value::Object(VmRef::new(ObjectData {
+            strings,
+            symbols: None,
+        }))
+    }
+
     /// Create an empty array Value.
     pub fn empty_array() -> Self {
         Value::Array(VmRef::new(Vec::new()))
     }
 
+    // -------------------------------------------------------------------------
+    // Packed f64 array support (TISH_PACKED_ARRAYS)
+    // -------------------------------------------------------------------------
+
+    /// Whether packed f64 arrays are enabled this run. Default: **off** (`TISH_PACKED_ARRAYS=1`
+    /// opts in). Checked at every creation site so flag changes take effect per-process.
+    /// The flag is intentionally backwards from the slot/JIT flags (those were default-on) to
+    /// keep the default binary behaviour byte-identical while we validate coverage.
+    #[inline]
+    pub fn packed_arrays_enabled() -> bool {
+        std::env::var("TISH_PACKED_ARRAYS").map(|v| v == "1").unwrap_or(false)
+    }
+
+    /// Wrap a `Vec<f64>` as a `Value::NumberArray`. Only call when `packed_arrays_enabled()`.
+    #[inline]
+    pub fn number_array(items: Vec<f64>) -> Self {
+        Value::NumberArray(VmRef::new(items))
+    }
+
+    /// Materialize a `Value::NumberArray` into a boxed `Value::Array`.
+    /// Called on the deopt path: any operation that doesn't have a packed fast path
+    /// (non-numeric push, getIndex-beyond-bounds, spread into non-numeric context, etc.)
+    /// converts once and continues on the generic path. The original `NumberArray` VmRef
+    /// is consumed; callers replace the `Value` in whatever container held it.
+    #[inline]
+    pub fn materialize_number_array(arr: &VmRef<Vec<f64>>) -> Value {
+        let nums = arr.borrow();
+        Value::Array(VmRef::new(nums.iter().map(|&n| Value::Number(n)).collect()))
+    }
+
+    /// If `self` is a `NumberArray`, materialise and return `Value::Array`; otherwise
+    /// return `self` unchanged. Convenience deopt for callers that pattern-match on `Array`.
+    #[inline]
+    pub fn coerce_number_array(self) -> Value {
+        match self {
+            Value::NumberArray(ref arr) => Value::materialize_number_array(arr),
+            other => other,
+        }
+    }
+
     /// Create an empty object Value.
     pub fn empty_object() -> Self {
         Value::Object(VmRef::new(ObjectData::default()))
@@ -595,7 +1203,7 @@ impl Value {
             Value::String(_) => "string",
             Value::Bool(_) => "boolean",
             Value::Null => "null",
-            Value::Array(_) => "object",
+            Value::Array(_) | Value::NumberArray(_) => "object",
             Value::Object(_) => "object",
             Value::Function(_) => "function",
             #[cfg(feature = "regex")]
@@ -694,3 +1302,49 @@ impl Value {
         }
     }
 }
+
+#[cfg(test)]
+mod number_to_string_tests {
+    use super::js_number_to_string;
+
+    #[test]
+    fn matches_javascript_number_tostring() {
+        // (value, expected) — every `expected` is what Node's `String(value)` produces.
+        let cases: &[(f64, &str)] = &[
+            (0.0, "0"),
+            (-0.0, "-0"),
+            (123.0, "123"),
+            (123.456, "123.456"),
+            (0.5, "0.5"),
+            (-123.456, "-123.456"),
+            (100000.0, "100000"),
+            // Decimal/exponential boundary on the large side: 1e21 flips to exponential.
+            (1e20, "100000000000000000000"),
+            (1e21, "1e+21"),
+            (21e18, "21000000000000000000"),
+            // Small side: 1e-6 is decimal, 1e-7 is exponential.
+            (1e-6, "0.000001"),
+            (1e-7, "1e-7"),
+            (9.5e-7, "9.5e-7"),
+            // Exponential with a multi-digit mantissa.
+            (6.022e23, "6.022e+23"),
+            (1.2345678901234568e21, "1.2345678901234568e+21"),
+            (1e100, "1e+100"),
+            (-1e21, "-1e+21"),
+            // Subnormal min and normal max.
+            (5e-324, "5e-324"),
+            (1.7976931348623157e308, "1.7976931348623157e+308"),
+            // Shortest round-trip mantissa (not full precision).
+            (0.1, "0.1"),
+            (0.1 + 0.2, "0.30000000000000004"),
+            // Non-finite.
+            (f64::INFINITY, "Infinity"),
+            (f64::NEG_INFINITY, "-Infinity"),
+            (f64::NAN, "NaN"),
+        ];
+        for &(value, expected) in cases {
+            assert_eq!(js_number_to_string(value), expected, "for {value:?}");
+        }
+    }
+}
+