zena:core

An immutable sequence of characters with value equality.

Strings are created from string literals, template literals, concatenation, slicing, and StringBuilder.

Base class for errors when a lookup operation fails.

Thrown when an array/sequence index is out of bounds.

Thrown when a key is not found in a map or similar collection.

Thrown by a synchronous for when an iterator's next() reports a Pending step — a value that is not available synchronously. Consume such an iterator with for await instead (docs/design/async-iteration.md).

Represents a present value.

Represents an absent value.

Result's storable counterpart: the same two arms as a sealed reference type, for when a result must outlive return position — an array of per-item outcomes, a field holding a deferred answer. Ok carries what the inline form's true arm does, Err the false arm's payload.

Reach for the inline Result<T, E> first: it allocates nothing. This type is for the positions inline tuples cannot occupy, and costs one allocation per outcome.

A value outcome.

An error outcome.

A bounded range with both start and end (exclusive). Represents [start, end) - includes start, excludes end.

A range from a start point to infinity/length. Represents [start, ∞) or [start, length).

A range from zero to an end point (exclusive). Represents [0, end).

A full range representing all elements. Represents [0, length).

The classes declared with the resource modifier — those holding something the garbage collector cannot reclaim, and therefore carrying a release obligation.

resource class R satisfies this without an implements clause, the way a case class satisfies Hashable. It exists to be bounded against: disown and adopt take a T extends Resource rather than any T, because moving a value between the affine and manually-managed regimes is only meaningful for something that has a disposal obligation to move.

There is deliberately no way to hold one. Nothing is assignable to Resource, because the only reference to a resource a program can name is a handle — Own<R>, Borrow<R>, Unmanaged<R> — and those are nominally distinct types that assign to no supertype at all. That is what keeps a widening conversion from dropping the permissions the handle carries, and it is a property of the handles rather than of this interface: the same applies to every supertype, Resource or otherwise.

Resource-ness is what this names; affineness is what Own<T> declares. They are separate properties — see ownership.md §"Resource-ness and affineness are different properties" — so this bound restricts neither Own<T> itself nor the ordinary classes it will eventually wrap.

The root of every resource hierarchy. A resource class with no explicit superclass extends this one, so the lifecycle flag has an ordinary in-language home rather than a field codegen injects, and disown/adopt read it with an ordinary method call rather than an intrinsic. Being the root is also what makes ownership.md §"Resource-ness is inherited" cheap to satisfy: single inheritance means a resource cannot also extend an ordinary class, so the rule that its chain is all resources is structural rather than a check.

Declaring no method that returns this is load-bearing, not incidental. That is the whole reason an arbitrary superclass is unsafe for a resource and this one is not.

Raised when a regime change is handed a resource in the wrong state: adopting one that was never disowned, or disowning one twice.

Both are programming errors rather than expected conditions — the resource was already claimed by someone else, or already released — so they throw rather than returning a Result. A tryAdopt handing back the branch can be added if a caller ever wants it.

Represents the string literals in a tagged template expression.

When you write tag\Hello ${name}!`` the tag function receives:

• strings: TemplateStringsArray containing ["Hello ", "!"]
• values: array containing [name]

Key properties:

• Immutable: The strings array cannot be modified.
• Cached: The same TemplateStringsArray instance is reused across invocations of the same tagged template expression.
• Interleaved: Strings and values alternate, with strings on both ends. For \a${x}b${y}c`: strings = ["a", "b", "c"], values = [x, y]. This means there is always strings.length == values.length + 1`.

The raw property provides access to the raw (unescaped) string literals, where escape sequences like \\n appear as two characters (\ and n) rather than being interpreted as a newline.

Example:

let tag = (strings: TemplateStringsArray, values: FixedArray<anyref>): String => {
  // strings[0] = "Line 1\nLine 2" (newline interpreted)
  // strings.raw[0] = "Line 1\\nLine 2" (backslash-n literal)
  return strings[0];
};
tag\`Line 1\\nLine 2\`;

An Iterator that yields elements matching a predicate.

An Iterable that lazily filters elements using a predicate.

Iterator over a FixedArray. Holds a reference to the array and tracks position.

A growable buffer for efficiently constructing binary data.

An append-only sequence of characters for efficient string construction.

StringReader - A cursor-based string parser that tracks byte positions.

Use StringReader for parsing to ensure slices are always at valid UTF-8 code point boundaries. Positions from mark() are safe to use with sliceBytes().

Example usage:

let r = new StringReader(input);
r.skipWhitespace();
let start = r.mark();
while (!r.isAtEnd && r.peekByte() != 34) {  // 34 = '"'
  r.advance();  // Move by code point (safe for Unicode)
}
let token = r.sliceFrom(start);  // Safe: positions from mark()

A type that can be used as a key in hash-based collections like HashMap and HashSet.

The contract: if two values are equal (per ==, which is a virtual call to operator == when the class defines one, and reference equality otherwise), they must return the same hashCode. The reverse is not required — unequal values may share a hash code, though fewer collisions means better performance.

A class that uses reference equality (no operator ==) should return an identity hash: a value that is unique per instance and stable for the lifetime of the instance, e.g. a counter assigned in the constructor.

Case classes automatically satisfy Hashable: the compiler generates a structural hashCode() (and operator ==) from their parameters. Primitives (i32, boolean, enums, and distinct types over them) also satisfy the Hashable constraint; they hash to their own value. Strings hash with FNV-1a, cached after the first computation.

A value holding something the garbage collector cannot reclaim.

dispose is symbol-keyed rather than name-keyed. dispose is a common enough method name that a class may already have one meaning something unrelated, and this is a protocol the language itself invokes implicitly — a silent collision would be a resource released at the wrong time. Call it as value.[Disposable.dispose]().

import { Disposable } from './ownership.zena';

class Descriptor implements Disposable {
  #handle: i32;
  new(this.#handle);
  [Disposable.dispose](): void { descriptorDrop(this.#handle); }
}

Disposal must be idempotent: dispose() may be called on an already disposed value and must not release the underlying resource twice. Until affine checking lands in O2, nothing statically prevents a double call, and a resource wrapper's state flag is what makes the second one a no-op.

A stateful iterator over elements of type T.

Usage pattern with let-pattern conditions:

let iter = collection.[Iterable.iterator]();
while (let (true, item) = iter.next()) {
  // use item
}

Design: Uses inline tuple returns for zero-allocation iteration.

• next() returns inline (true, T) when there's an element
• next() returns inline (false, _) when exhausted

A collection that can produce an Iterator.

A sequence with a length and indexed reads.

This is the read-only view; MutableArray adds indexed writes. The constructors build the standard implementations — new Array() is a GrowableArray and new Array.fixed(n, value) a FixedArray — and are typed as those classes, so the result has the class's full API. (The modules declaring those classes import this one back; classes and interfaces may cross an import cycle.)

Common iteration utilities for any collection that implements Iterable.

Opaque host-side stack-trace handle.

A value that is either present (Some) or absent (None).

Result<T, E> — a value that is either an ok payload or an error payload.

Unlike Option, this is an inline multi-value union, not a heap type: it compiles to WebAssembly multi-value returns, so returning an ok or an error costs no allocation. That is why it is a type alias rather than a class hierarchy — see docs/design/result-option.md.

There are three lanes, not two, so that each lane is type-homogeneous: the discriminant, the ok payload, and the error payload. The unused payload in each arm is a hole (_).

import { Result } from './result.zena';

let checkedSub = (a: i32, b: i32): Result<i32, String> => {
  if (b > a) {
    return (false, _, "underflow");
  }
  return (true, a - b, _);
};

if (let (true, v, _) = checkedSub(10, 4)) {
  // v is 6
}

Inline tuples are return-position-only, so Result<T, E> may name a function's return type but cannot be stored in a variable, field, or collection. To keep a result around, store it as an Outcome below, or match it and store the payload.

Union type of all range types.

The owning reference to a resource. Affine: it may be moved, returned or stored, but not duplicated, and it is released when it leaves scope unmoved.

Erased at codegen: a distinct type is nominally distinct for checking but shares its target's representation, so a handle costs no allocation and no indirection. The three differ in permissions, not data.

Own<T> is what declares affineness; resource class declares resource-ness. The two are separate on purpose — see ownership.md §"Resource-ness and affineness are different properties" — which is why Own<T> will also apply to ordinary classes (from a provably exclusive source) once layer 4 needs it.

A borrowed reference. Freely copied, but second-class: it may not be returned (except derived from a single borrow parameter), stored in a field or array, or captured by a closure. Never releases what it points at.

At unrestricted instantiations Borrow<T> is the identity — Borrow<i32> is i32 — which is what keeps container APIs from forking.

A disowned resource: aliasable like an ordinary reference, and never implicitly dropped. You must dispose() it yourself or adopt() it back into the affine world.

This is the population using was designed for. Entering it costs leak-freedom and compile-time use-after-dispose detection; it costs neither type soundness nor memory safety, because the state flag turns a bad adopt into a clean error rather than a double free.

A value that may not be duplicated and may not outlive the extent it derives from — the corner of the universe table where both restrictions bind (ownership.md §"Scoped: the fourth corner"). The population is borrow-derived futures and iterators: an async function that holds a Borrow across await returns Scoped<Future<T>>, so the frame holding the borrow cannot escape the borrow's extent.

A scoped value must be consumed exactly once on every path: a scoped future by await or a move, a scoped iterator by for/in. It may not be stored in a field, container, record, or tuple, and may not be captured by a closure. A first-class Future<T> coerces to Scoped<Future<T>>; there is no way back.

Scoped<R> when T carries a second-class type — a scoped value, a restricted borrow, or a scoped type parameter — and R otherwise (ownership.md §"Combinator audit", docs/design/type-operators.md). For a generic whose result must be scoped exactly when an input is: Future.allSettled<scoped T> returns ScopedFrom<T, Future<Array<Outcome<Awaited<T>, Error>>>>, so a call over scoped futures yields a scoped result the caller must consume, and a call over ordinary futures yields the ordinary future it always did. Inside the generic body the operator reads as Scoped<R>; substitution collapses it once T is known.

Type alias for template tag functions.

Example usage:

const html: TemplateTag<String> = (strings, values) => {
  // strings[0], strings[1], etc. are the literal parts
  // values[0], values[1], etc. are the interpolated expressions
  // strings.raw gives access to raw (unescaped) strings
  return '...';
};

const result = html`<div>${name}</div>`;

Returns the ASCII lowercase of b, leaving every other byte or code point unchanged.

Returns the ASCII uppercase of b.

Creates a Some containing the given value.

The hash code of a value, dispatched on its static type: primitives hash by value, Strings by content, and classes through hashCode().

This is what hash-based collections call. Prefer it over hashCode() — it works for primitives, which have no methods.

Whether two values of the same type are equal, dispatched on their static type: primitives compare by value, Strings by content, and classes through operator == when the class defines one and by reference otherwise.

Leaves the affine regime: takes the owning handle and hands back an aliasable one that is never implicitly dropped.

let raw: Unmanaged<Descriptor> = disown(f);   // f is consumed
// … alias it, store it in a field, put it in an ordinary Array …
let f2: Own<Descriptor> = adopt(raw);         // back under implicit drop

The handles are erased, so this re-types the object rather than allocating anything: Own<T> and Unmanaged<T> lower to the same wasm type, and the body compiles to an identity function returning its argument. The call itself is not yet inlined away.

Requires the resource to be owned and leaves it disowned, so disowning the same resource twice throws rather than handing out two unmanaged aliases with one disposal obligation between them.

disown consumes its argument. Otherwise an Own that will implicitly drop would coexist with an Unmanaged alias to the same resource, and the drop would run under an alias that outlives it. Move checking enforces the consumption for local bindings — a caller that keeps using the original Own after disowning it gets a compile error, through the ordinary rule that an argument to an Own parameter is a move. The flag still guards the routes the checker does not track, such as an Own read out of a field.

The cast is legal here and nowhere else: Own<T> and Unmanaged<T> are opaque types declared in this file, and both erase to T, so re-labelling one as the other mints nothing. See ownership.md §"Handles are not forgeable" — outside this file the same cast is a diagnostic, which is what makes disown and adopt the only doors between the two regimes.

Re-enters the affine regime: takes a disowned handle back under implicit drop, so it is released at scope exit again.

The inverse of disown, and the only way back — Unmanaged<R> has no user-callable dispose, since it is not an owner and cannot call the consuming form. A disowned resource is either scoped with using or adopted back.

Throws when the resource is not in the disowned state: owned means something else adopted it first, so two racing adopters do not both succeed — the loser gets a clear error rather than a second owner and, once implicit drop lands, a double free.

dropped throws too: every consuming dispose sets it, so adopting an already-released resource is reported as exactly that.

adopt cannot retract aliases. Aliasability is the point of the disowned state, so the flag is the only defence here, by design.

The elements of a scoped iterator mapped through f. Driving the result drives it, inside the same extent — the input is consumed (a scoped iterator is driven exactly once), and the result derives from the same borrow, so it is scoped too.

The elements of a scoped iterator for which keep answers true.

At most the first count elements of a scoped iterator. The loop is always entered — every path out of this body must consume it — so with count <= 0 one element is still pulled from the source before the frame is disposed.

A template tag that strips the source indentation from a multi-line template literal, so a block of text can be written at the indentation of the code around it and still come out flush left:

let usage = dedent`
  zena build <entry>
    -o <path>   where to write the module
`;
// "zena build <entry>\n  -o <path>   where to write the module"

The rules:

• The opening line is dropped, along with its line break, when it is blank — which it is in the form above, where the content starts on the line after the backtick. The closing line is dropped the same way. Neither is dropped when it has content on it: a line with content is a line, and it takes part in the rule below like any other.
• The indentation removed from every remaining line is the longest common prefix of the indentation of the lines that have content on them. It is compared byte for byte, so a file that mixes tabs and spaces dedents by what its lines actually share rather than by a count that assumes a tab width.
• Blank lines are ignored when computing that prefix and come out empty, so a line of leftover trailing spaces is not what decides the result.
• Interpolated values are inserted verbatim. A value containing newlines is not re-indented, and its newlines do not start lines that participate in the computation: only indentation written in the literal counts. A line that starts with a value is a content line, and the whitespace before the value is its indentation.

Interpolations must be Strings — a tag receives its values without the conversion ${} performs in an untagged template literal, so write dedent`count: ${`${n}`}` (or i32ToString(n)) for a number.

The text dedented is the cooked strings, so an escape is processed before the indentation is measured: a \n written as an escape breaks a line here exactly as a real newline does. Today that is theory rather than practice — a tagged template whose literal contains any escape sequence fails to compile, whatever the tag (see elematic/zena#84).

Its argument, unchanged: fixed([1, 2, 3]).

The parameter supplies the mutable context, so a literal argument builds directly as a FixedArray — a mutable literal in expression position, where no annotation can say so. The identity body inlines away, leaving the bare allocation.

A growable array from an array literal: growable([1, 2, 3]).

The parameter supplies the mutable context, so the literal builds directly as a FixedArray and is adopted as the backing storage — no copy, unlike GrowableArray.from over an interface-typed source. Until literal decorators land, this is the concise spelling for a growable array with initial contents.

Create a new ByteArray of the specified size, filled with zeros.

Copy bytes from source to destination.

Writes an i32 to a buffer. Buffer must have at least 11 bytes. Returns (startPos, endPos) where the digits are in buffer[startPos..endPos).

Writes a u32 to a buffer. Buffer must have at least 10 bytes. Returns (startPos, endPos).

Writes an i64 to a buffer. Buffer must have at least 20 bytes. Returns (startPos, endPos).

Writes a u64 to a buffer. Buffer must have at least 20 bytes. Returns (startPos, endPos).

Converts an i32 to its decimal string representation.

Converts a u32 to its decimal string representation.

Converts an i64 to its decimal string representation.

Converts a u64 to its decimal string representation.

Converts a bool to "true" or "false".

Parse a decimal integer from a string, with optional leading sign. Returns inline (true, value) on success, inline (false, _) on failure. Fails if the string is empty or contains non-digit characters (after optional sign).

The f64 nearest to d * 10^p, correctly rounded. d is the decimal significand as an integer below 2^64 and p its decimal exponent. inexact says the true value lies strictly between d and d + 1 — the caller had more digits than it could keep — and tail is that leftover fraction scaled by 2^11.

With 19 or fewer significant digits inexact is false and the result is the correctly rounded one, always. Beyond that the significand no longer fits: normalizing d to 64 bits leaves only 64 - bits(d) low bits for the remainder, so the value is placed to within half of the last of them and can land on the wrong side of a rounding boundary that falls inside that gap. Measured against a correctly-rounded implementation this is about one input in five thousand of more than 19 significant digits, always by one ulp (dev/fp-difftest.js measures it). Closing it needs an exact-arithmetic fallback, which the algorithm this comes from also leaves to its caller.

The shortest decimal string that reads back as this f32. The f32 interval is used, not the f64 one the promoted value would have, so 0.1 as f32 prints "0.1" rather than "0.10000000149011612".

The shortest decimal string that reads back as this f64.

value rounded to sigDigits significant decimal digits, in the same format f64ToString uses. sigDigits is clamped to [1, 17].

Parses a decimal (or hexadecimal) number string to the NEAREST f64, correctly rounded.

The significand is accumulated as an integer and the exponent tracked alongside, so no rounding happens until the single decimalToF64 at the end. Digits beyond the nineteenth cannot change the result except through the tie they might break, so they are folded into a sticky low digit rather than dropped.

Parse an i64 integer from a string, supporting optional leading sign, optional hex prefix (0x or 0X), and optional underscores (_). Returns inline (true, value) on success, inline (false, _) on failure.

The singleton None instance.