Sketch out the MVP standard library

[Copilot]

• Analyze existing standard library documentation and design patterns
• Draft MVP standard library design document with phases and priorities
• Update docs/design/standard-library.md with the MVP plan
• Address PR feedback:
  • Rename types for JS familiarity: FixedArray<T> (WASM primitive), Array<T> (growable)
  • Add Sequence<T> interface for read-only indexed access
  • Add ReadonlyArray<T> for immutable arrays
  • Add discussion of StringBuilder alternatives (Rope, Array.join())
  • Split math module between WASM intrinsics and library functions
• Fix status inconsistency: clarify FixedArray rename is pending (🔄)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Sketch out the MVP standard library</issue_title>
<issue_description>We should figure out what a good, but basic, standard library we aim for for the first realistically usable programs.

An example of an early class of programs we want to target is a parser. Assuming I/O is taken care of separately, what do we need in the language?

Dart has a well-design standard library we could take inspiration from. Some interfaces and classes we might want:

• List<T> - the abstract list indexable interface
• `ArrayList - a list backed by arrays
• Array<T> - a non-growable WASM-native array. Note: Do we need growable and non-growable List interfaces? Or should Array not implement List, but some other interface?
• Set<T> - interface or class? - should this also be the default hashing-based implementation? It would be nicer to do new Set() than new HashSet().
• Map<T> - interface or class?
• Collection<T> - nice, but do we need it?
• Date - should we even try a simple date, or should we figure out a strategy for using the JavaScript Temporal API via one of the Rust temporal implementation?
• Regex - often quite useful for parsers. How do we do this in WASM? https://github.com/google/re2-wasm ?
• zena:math - what kind of math functions do we need at first? Trig, min/max/clamp?
• Iterator<T> and Iterable<T>
• Promise<T>
• some kind of scheduler library we can use for timeouts and intervals

What else?

This issue will be closed by writing an initial design doc sketching out the plan for the standard library, hopefully including priorities and phases.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [stdlib] Sketch out the MVP standard library #13

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[justinfagnani]

@copilot

Do we want an interface for not-necessarily-growable indexed collections so that we have a common interface between Array and List? We should also have ReadonlyArray<T> which is fixed length due to immutability. I've seen the interface Sequence used before.

I wonder about the names here. List is used in Java and Dart, but JavaScript/TypeScript is the most popular language now and a lot of people are used to Array. Can Array be the indexed, growable interface and we come up with a new name for the WASAM-array backed data type? ie FixedArray?

I think most people would want growable arrays or fully immutable arrays. Fixed-length mutable arrays are kind of an anomaly in high level languages.

[Copilot]

Updated the naming scheme in commit 0dfa002:

• FixedArray<T> - WASM GC array primitive (fixed-length, mutable)
• Array<T> - Growable array interface (JS-familiar naming)
• Sequence<T> - Read-only indexed access interface (common abstraction)
• ReadonlyArray<T> - Immutable fixed-length array wrapper

The Sequence<T> interface provides the common abstraction for all indexed collections, enabling code to work with any array type without caring about mutability.

[justinfagnani]

@copilot

Would we need this if we had multiple internal string implementations, like a Rope, and optimized the + operator? Or is this approach just a lot simpler on us? Array.join() could be an option too.

[Copilot]

Added a discussion in commit 0dfa002. Alternatives considered:

1. Rope: O(log n) concat but adds complexity and may hurt small string performance
2. Array.join(): Already included in the Array<T> interface

Recommendation: Start with StringBuilder as the simple explicit approach. Consider Rope as a future optimization if profiling shows string concatenation is a bottleneck.

[justinfagnani]

@copilot

Do we want to split the math library between what's available as WASM instructions and what we have to build into the library, like the trig functions?

[Copilot]

Split the math module in commit 0dfa002:

WASM Intrinsics (zero-cost): floor, ceil, trunc, round, sqrt, absF32, minF32, maxF32, copysign

Library Functions (Zena or host): Trig functions (sin, cos, tan, etc.), exponentials (exp, log, pow), integer operations (abs, min, max, clamp)

Recommendation: Start with host delegation for trig/transcendental functions, consider pure Zena implementations later for environments without host math support.