Standard library

The Khora standard library is written primarily in Khora and ships with the compiler toolchain. It provides the stable vocabulary and cross-package contracts that ordinary programs need without turning every database, telemetry backend, or platform integration into std.

Major areas

The current standard library includes APIs for:

• strings and collections, in std::core;
• JSON encoding and decoding, in std::json;
• files, in std::fs, and processes, in std::process and std::process::shell;
• the environment, in std::env;
• randomness, in std::random;
• clocks and sleeping, in std::clock;
• describing and decoding untrusted input, in std::schema;
• typed configuration, in std::config;
• retries and backoff schedules, in std::resilience;
• civil dates and offsets, in std::time;
• exact Decimal arithmetic, in std::decimal;
• HTTP client/server building blocks, in std::net::http, over std::net::socket;
• TLS, in std::net::tls;
• structured concurrency and shared state, in std::core;
• database capability and row/cell vocabulary, in std::db;
• tracing context and W3C propagation vocabulary, in std::trace;
• structured logging and writing to standard error, in std::log;
• capability permissions, in std::permissions.

Every entry links, which they did not all do: civil dates and offsets and exact Decimal arithmetic were bare prose beside neighbours that linked, so the two modules a financial program reaches for first had to be guessed at by URL.

Three of those are new and easy to miss:

std::clock holds the Clock capability, which used to live in std::env. import std::env::{Clock} no longer resolves. The split also gave Clock a sleep, which is an operation on the capability so that a fake clock is one line in a test.

std::config reads settings out of the environment, types them, and reports every bad key in one pass rather than one restart per key. See the cookbook recipe.

std::resilience holds Schedule, retry, retry_while and repeat, which used to be a bare attempt counter in std::core. See Retrying a flaky call.

std::schema describes the shape of a value once and decodes it from anywhere. It is the newest, and the one that changes how the others are meant to be used: a Schema<Settings> reads the same settings from the environment, from a request body or from a test fixture, because the description does not know where the bytes came from. Schemas is the model; Decode untrusted input is a program that runs.

Choosing a collection

List<A> is a linked sequence, for ordered transformation and iteration. Vector<A> is a growable contiguous sequence, for accumulation and indexing. Map<K, V> is a mutable hash table; Dict<K, V> is a persistent ordered map.

The language does not change with the choice: ordinary calls, methods, pipelines, lambdas, for and pattern matching work the same over all four. The operations themselves are in std::core.

The mutable ones — Vector and Map — stay fiber-local. Where several fibers need one evolving value, that is a Shared boundary or a capability, not a container passed around; Sharing says why wrapping the type name in a shareable record does not make it safe.

What belongs in std

Khora keeps shared contracts in the standard library and leaves fast-moving implementations in packages. For example, Db, transaction semantics, and database cell types belong in std; PostgreSQL, SQLite, and Cloudflare D1 drivers do not. Trace vocabulary and propagation belong in std; vendor exporters do not.

The same principle keeps the IANA time-zone database out of the compatibility promise while retaining stable date/time/offset types.

Generated API reference

This page is the curated entry point; the API reference pages beneath it are generated by khora doc from the /// and //! comments in std/ at the revision being documented. Every exported type, trait, effect, function and constant is there, with its signature and whatever its author wrote about it.

They are checked rather than trusted. khora doc --check runs in the project baseline and fails if the checked-in pages no longer match the source, so a page cannot quietly drift from the declaration it describes.

Two things the reference does not yet do, both tracked as roadmap 13.15:

• Examples are not compiled. Code in a doc comment is prose today. Making ```khora blocks run as tests is the next slice, and until it lands an example can be wrong without anything noticing.
• There are no cross-links. A signature mentioning Decimal names it but does not link to it.

Use the Language Reference for the language, this section for the library, and the generated pages beneath it for exact declarations.