Standard library

Aura’s core stdlib is intentionally small (RFC-007, RFC-000 batteries-included-but-modular). In this repository, packages live under std/.

Packages today

Builtins such as Array<T> and core scalars are part of the language, not a separate import. String methods (indexOf, split, trim, toInt, …) are language surface — see Types and the cheatsheet.

std.io

Console, process, and file helpers (runtime aura_* intrinsics). Strict file APIs throw a String message on failure (missing path, I/O error, oversized file, embedded NUL). Soft tryReadFile returns null instead. Text is treated as a regular-file UTF-8 byte sequence (no embedded NUL); max size 256 MiB.

Console

Process (C12b–e)

Task outcomes

join returns Result<T, TaskError>. taskErrorTypeName exposes the typed failure name when available; taskErrorSpanStart and taskErrorSpanEnd expose the retained source span, and taskErrorSourceId exposes its stable throw-origin identity without borrowing the child task frame.

Pass user args after -- with the CLI (CLI):

aura run my_pkg -- --flag value
cargo run -p aura-cli -- run corpus/std_io/args -- hello
printf 'line\n' | cargo run -p aura-cli -- run corpus/std_io/stdin

Files (C11a / C12p)

Typical use (explicit import or auto-prelude on package builds):

package main

import std.io as Io

fun main() {
  Io.println("Hello, Aura")
  val argv = Io.args()
  if (argv.len > 1) {
    Io.println(argv.get(1))
  }
  Io.writeFile("out.txt", "hi")
  val s = Io.tryReadFile("out.txt")
  if (s != null) {
    Io.println(s)
  }
}

Corpus:

aura run corpus/std_io/app
aura run corpus/std_io/prelude
aura run corpus/std_io/files
aura run corpus/std_io/try_read_file
aura run corpus/std_io/args -- hello
aura run corpus/std_io/stdin
aura run corpus/std_io/exit
# monorepo: cargo run -p aura-cli -- run corpus/std_io/files

Dogfood CLI that ties args + soft read + String tools: examples/wc (README).

std.assert

std.assert.assert(condition) is the runtime assertion primitive. Use it with aura test and @test functions:

aura run corpus/std_assert/app

The RFC-011 names are assertTrue, generic assertEqual, generic assertNotNull, and assertFails. The typed assertEqInt, assertEqString, and assertEqBool helpers remain alpha compatibility aliases; the language-level assert_eq helpers are separate builtins.

benchmark, snapshot, and property provide deterministic advanced testing hooks. Benchmarks use AURA_BENCH_ITERATIONS; snapshots read from AURA_SNAPSHOT_DIR and can be created or updated with AURA_UPDATE_SNAPSHOTS=1; property checks execute the requested number of cases. The CLI runner and richer generator/report protocols remain separate follow-up work.

std.collections

List<T>, List.of(...), listOf(...), and list<T>() provide the growable list API backed by owning Array<T> storage. map<R> supports element-type transforms. iterator() and toArray() return independent snapshots, so later list mutation cannot invalidate or alias the returned values.

See Arrays for HOF usage and capture limits.

aura run corpus/std_collections/app
aura run corpus/std_collections/hashmap
aura run corpus/std_collections/hashmap_str
aura run corpus/std_collections/hashmap_int
aura run corpus/std_collections/hashset_int
aura run corpus/std_collections/hof
aura run corpus/std_collections/hof_str
aura run corpus/std_collections/join

Hash collection HOFs are free functions because methods cannot declare their own type parameters yet (C2b). They return arrays in logical table order and skip empty/tombstone slots; they do not mutate the source collection.

HashMap.entries() likewise returns a fresh, shallow structural snapshot of HashMapEntry<K,V> pairs. It preserves key/value pairing and can be consumed directly with for-in, but it is not a live iterator or entry view: changing an entry cannot mutate the source map.

HashMap.entry(key) returns a key-based mutation handle when the key exists. Calling handle.set(value) replaces only that existing value and returns false if it was removed. The handle retains the map and re-resolves its key on every update, so rehash and GC cannot make it stale.

HashMap.liveEntry(key) returns an invalidation-checked live view when the key exists. Its get() and set(value) operate only while isValid() is true; inserting, removing, clearing, or growing/rehashing the map invalidates the view. Updating its own value preserves validity.

Snapshot iterators are safe across source mutation, rehash, and clear. Live iterators retain their source and become terminal after structural mutation; isValid() reports the epoch check and next() returns null once invalid. Value replacement remains visible while a cursor is valid. Map live entry iterators yield HashMapLiveEntry views, whose get() and set(value) are also invalidation-checked.

std.error

Shared non-throwing error surface used by filesystem, OS, DNS, network, and HTTP adapters.

std.bytes

The legacy Buffer.push and Buffer.get integer operations remain available for compatibility. Binary protocol code should use Byte and the explicit buffer methods so payloads never pass through UTF-8 String conversion.

std.encoding

std.json

Value exposes bounded object-member and array traversal. ParseOptions supports maxBytes, maxDepth, and explicit duplicate-key behavior (Reject, FirstWins, LastWins). Typed decoding supports primitives, Array<Int>, Array<Bool>, Array<String>, recursively nested primitive arrays, and recursive application classes with generic, nullable, nested-class, struct, unit-enum, and primitive/class-array fields. Payload-bearing enum mapping remains outside this bounded contract.

std.mime

std.fs

std.os

std.net

std.net accepts endpoint strings on POSIX targets. A numeric endpoint such as "8080" binds/connects to loopback; use "0.0.0.0:8080" for all IPv4 interfaces or "[::]:8080" for IPv6. Handles are owned ForeignHandle<Int> resources and async operations preserve them across suspension.

std.dns

std.url

std.http

Bounded HTTP/1.1 values and loopback client/server helpers built on std.net. Server handlers receive scoped Request and Response objects; raw foreign handles remain package-private.

The bounded server accepts origin-form GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS requests. Other methods receive a bounded 405 response.

std.stream

std.time

All clocks and deadlines are monotonic; wall-clock changes do not affect them.

std.task

std.sync

These primitives are nonblocking. tryLock, tryRead, and tryWrite return false instead of blocking an async worker.

std.signal

std.log

std.metrics

std.test

std.crypto

The alpha contract provides Digest, TlsConfig, TlsConnection, randomBytes, randomBytesBuffer, md5Bytes, sha256, sha256Bytes, hmacSha256, hmacSha256Bytes, pbkdf2Sha256, and constantTimeEquals. Binary crypto APIs accept and return std.bytes.Buffer, so NUL bytes are preserved. PBKDF2-HMAC-SHA-256 supports SCRAM-SHA-256 key derivation; hashPassword and verifyPassword provide versioned salted password records; randomness, hashes, HMAC, PBKDF2, and constant time comparison are backed by the native runtime.

std.tls

TLS async operations use the underlying TCP readiness scheduler. A cancelled read or write closes the TLS session and wakes the socket wait, preventing a cancelled task from retaining a blocked descriptor.

std.reflect

The package provides compiler-backed typeOf<T>, typeIdOf<T>, type-kind classification, and declaration metadata. Primitive types are always reflectable; user classes, structs, enums, and interfaces opt in with @reflect. Only public fields and methods are exposed. Closed generic class and interface metadata uses the concrete monomorph name and substitutes type parameters in exposed field and method return types.

Bounded protocol packages

std.tls, std.websocket, std.compress, and std.multipart provide runtime-backed bounded implementations with explicit size and platform limits. Unix sockets, HTTP/2/3, and QUIC remain reserved without a public package until their ownership and capability contracts are settled.

How the CLI finds std.*

• Auto-prelude std.io for package builds
• Path resolution for any std.* package:
  1. AURA_STD (directory that contains package directories)
  2. Walk-up from the package looking for monorepo std/<pkg>
  3. Release install: share/aura/std/<pkg> next to the toolchain
  4. Embedded copy materialized under ~/.cache/aura/<version>/std/

After a normal install (or cargo install of a recent CLI), you should not need to declare std.io = { path = "..." } in app aura.toml.

What is not in core (by design)

Application frameworks, DI containers, ORM/HTTP stacks stay out of core RFCs. Expect those as ecosystem packages later, not as stdlib defaults.

Next

• Packages
• CLI
• Testing
• RFC-007