Strings: a lazily materialised host string has a base class, instead of passing null to a string parameter

[lahma]

A host whose string text is expensive to produce — a database blob, a projected document field, a payload behind a native handle — had exactly one way to say so: derive from JsString and pass null to a constructor whose parameter is typed string.

// Jint.Tests.PublicInterface/LazyHostStringTests.cs, before this PR
private sealed class LazyHostString : JsString
{
    public LazyHostString(string value) : base(null) { … }

    public override string ToString() { if (_materialized is null) { … } return _materialized; }
    public override int Length => _encoded.Length;
    public override char this[int index] => (char) _encoded[index];
}

Everything that follows from that null — which members must be overridden, which ones only avoid materialising, that the host owns its own memoization — lived in JsString's <remarks> and in that test's own <summary>. Nothing checked any of it. Jint.Tests.PublicInterface does not enable nullable reference types, which is why base(null) compiles there at all; a host on a modern project template writes base(null!), suppressing a warning about a contract nobody wrote down. RavenDB has the same shape in its own tree (RavenApiUsageTests.CustomString).

What this adds

public abstract class LazyJsString : JsString
{
    protected LazyJsString(int length);
    protected abstract string Materialize();
    public override int Length { get; }           // the constructor's value; never materialises
    public override char this[int index] { get; } // ToString()[index] by default
    public sealed override string ToString();
}

sealed class DocumentField : LazyJsString
{
    private readonly byte[] _utf8;

    public DocumentField(byte[] utf8, int length) : base(length) => _utf8 = utf8;

    protected override string Materialize() => Encoding.UTF8.GetString(_utf8);
}

Four things move from prose into the type:

• The base memoizes, and ToString() is sealed so the memoization cannot be bypassed. "Materialize() runs at most once" is a property of this class rather than something every host re-implements.
• Length never materialises, because it is the value handed to the constructor. That is the whole point: str.length, truthiness, and the length comparison JsString.Equals(JsString) performs first all resolve from it, so field === 'yes' against a 40 KB value costs nothing.
• Materialize() returning null is refused — an InvalidOperationException naming the type, thrown where the mistake is, rather than a null reaching the engine and surfacing as a NullReferenceException somewhere else entirely.
• A length that is not a string length is refused at construction — ArgumentOutOfRangeException for a negative one, and for one longer than a JavaScript string may be.

Length and the indexer stay virtual. The indexer is the one worth overriding: a store that can produce a single character without decoding the whole value should, and then character access joins the list of things that never materialise — which is exactly what the rewritten LazyHostString does, and why its counts below are unchanged.

Memoization is a plain unsynchronised field write, deliberately. An Engine rejects concurrent use, so every read the engine makes is on one thread. A host reading the same instance from several of its own threads may see Materialize() run twice and different callers receive different (but equal) string instances; nothing tears, because the field is only ever written with a complete value. A lock would buy a guarantee no supported usage needs, on a type whose whole purpose is to be cheap.

The member set

member	before: a base(null) subclass	after: a LazyJsString subclass
ToString()	mandatory — the base returns the null field	sealed; supply Materialize() instead
Length	mandatory — the base is _value.Length, i.e. an NRE	not needed; the constructor takes it
this[int]	mandatory for any character access — the base is _value[index]	optional, and worth it
memoization	by hand, in every host	the base class
Equals(JsString) / Equals(string) / GetHashCode()	optional, only to stay allocation-free	unchanged — same trade

So three mandatory overrides plus a hand-written memo become one method.

Host-contract verification

The one obligation a lazy string takes on in exchange for being asked nothing until it is read is that the length it declares is the length it produces. The engine trusts the declared length on every path that can answer from it alone and never re-checks, so a mismatch is silent and consequential: a value equal to 'abc' compares unequal to it, and an index the host considers in range reads past the end.

LazyJsString therefore checks the two against each other at materialisation, where both answers exist for the first time, under the usual if (HostContractVerification.Enabled) gate. It is one integer comparison on the path that has just done the expensive part, and it needs no out-of-assembly gate — nothing in Jint derives from this class, so every instance reaching it is a host type by construction. LazyHostStringTests pins both sides of the gate: with verification on the disagreement throws, naming the type and both lengths; with it off the check is not merely skipped but not emitted, the lie goes through, and the host sees the broken behaviour the message describes.

That the base's Length itself never materialises is true by construction rather than by verification, and is pinned by NothingThatOnlyNeedsTheLengthMaterializes.

The counter, before and after

The rewritten LazyHostString counts Materialize() calls. The counts were measured against the current base(null) shape first, and are identical after — which is the result to want: the base class is a better way to write the same thing, not a behaviour change.

script	materialisations
host.length, for (…; i < host.length; …)	0
typeof host, !!host, host ? 1 : 0	0
host[0], host.charAt(1), host.charCodeAt(2)	0 (this host overrides the indexer)
host === host	0
host === 'abcd', host !== 'ab', host == 'abcd' — lengths differ	0
two lazy strings of different lengths compared to each other	0 and 0
host in obj, obj[host] = 1, ({ [host]: 1 }), new Map().set(host, 1)	1
JSON.stringify(host) / { value: host } / [host]	1
host + '', `${host}`, String(host), host.toUpperCase()	1
host === 'abd' — same length, different text	1
all of the above on one instance, in one script	1

Two entries were on the "check, do not assume" list, and the answer is that they do need the text, so they are asserted as exactly 1 rather than 0:

• Using the value as a property key. A key is a string plus its ordinal hash and neither can be answered from a length, so host in obj, obj[host] = … and a computed key in an object literal all materialise. This is the one that surprises, and the README and the test now both say so.
• JSON.stringify of a containing object. It writes the characters out; there is nothing to defer.

The counter reaches 1 on the first read that needs the text and stays there for every subsequent read — which is the memoization, now the base class's job rather than each host's.

Compatibility

Nothing is removed and nothing changes for existing code. public JsString(string) still accepts null, the old shape still works, and Jint's own SlicedString / ConcatenatedString are still built on it. RavenDB's CustomString compiles and passes unchanged — RavenApiUsageTests keeps it deliberately and now says why, so a later cleanup does not remove the only thing proving the old spelling still works. LazyJsString is the supported spelling from v5 on; the migration note is docs/v5-migration.md §5.

JsString._value stays declared non-nullable. Its nullability is an internal matter with every read site already documented and commented; the dishonesty this PR is about is the public one.

Verification

• dotnet build -c Release — clean, with TreatWarningsAsErrors on.
• Jint.Tests (net472 / net8.0 / net10.0) and Jint.Tests.PublicInterface (net472 / net10.0), each run twice — once plain, once with JINT_HOST_CONTRACT_VERIFICATION=1. All green.
• Jint.Tests.Test262: 102,495 passed, 0 failed, 189 skipped.
• The five API baselines were regenerated by running the suite and copying .received.txt over .verified.txt. The diff is the new type and nothing else, on all five.

No benchmarks were run, and no string fast path was touched: the verifier lives inside LazyJsString's own cold materialisation path, not in JsString.Equals, Length, or any lane a flat string reaches.

🤖 Generated with Claude Code

https://claude.ai/code/session_014W5mbjGhyvgAS4pivXoc4S

[sebastienros]

What about other JsString sub-classes for concatenation. One could have the prefix as another JsString. There are lots of options for optimizations based on the operator.

[lahma]

You are right, and chasing this turned up something worse than the case you were pointing at — filed as #3350.

Taking the operator question first, because the answer is measurable. s += x and s = s + x mean the same thing and do not cost the same thing:

shape	20,000 iters	40,000 iters	scaling
s += x	25 ms	13 ms	flat
s = s + x	463 ms	1,626 ms	3.5× for 2× the work — quadratic
s = x + s	485 ms	—	quadratic

+= lands in JintAssignmentExpression.cs:260-273 and gets ConcatenatedString + Append, so it is StringBuilder-backed and linear. Plain + goes through ApplyAdditionToPrimitives (JintBinaryExpression.cs:1494), which does TypeConverter.ToString on both sides and string.Concat — no deferral, so each iteration copies the whole accumulated left operand.

We evaluated a rope in July and recorded NO-GO. That verdict was correct for what it measured and wrong as a general conclusion: every accumulating lane in StringConcatLargeBenchmark uses s += chunk, which was already linear, and ConcatLargePair rebuilds a fresh pair each iteration so its left operand never grows. The quadratic shape was never in the suite.

On your actual suggestion — holding the prefix as another JsString — that is the mechanism this needs, and the reason is not just deferral. + cannot reuse ConcatenatedString at all, because it is mutable; the class says so itself at JsString.cs:656 (growing the buffer and returning this would let a caller append into a value still reachable from where it was read). += only gets away with it because the assignment replaces the receiver, which is what wasMutatedInPlace is tracking. An immutable two-child node is shareable, which is exactly the property + requires — and it is the only thing that helps prepend, which the += lane can never reach.

Suggested order in the issue is to add the missing s = s + x / s = x + s lanes first so this is judged on a gate-mode number rather than my REPL timings, then decide on the node. The cost July identified still stands and is the real thing to weigh: every JsString consumer that does not route through ToString() has to handle a two-child node, and Length is virtual there, so a flattening bug surfaces as a wrong length rather than a crash.

On LazyJsString specifically: it composes with this rather than competing. It is a leaf like any other today, and concatenating one forces Materialize() — a host's database read — even when the result is only ever measured. An immutable node would defer that too.