# Standard library URL: /docs/stdlib Markdown: /docs/stdlib.md > Public std signatures generated from compiler/std/INDEX.md, with current JS limitations. {/* Generated by scripts/generate-stdlib.mjs. Edit compiler/std/INDEX.md for signatures. */} The source-built compiler embeds this standard library. This inventory is generated from [compiler/std/INDEX.md](https://github.com/icantcodefyi/sakura-lang/blob/master/compiler/std/INDEX.md). The signature blocks below are API declarations, not standalone programs. Their owning modules are checked and their tests exercised by `sakura test --std`. Regenerate this page from `website/` with `bun scripts/generate-stdlib.mjs`. Use [`sakura doc`](/docs/agents/doc) for offline type-pattern search and symbol documentation. The [capabilities tour](/docs/tour/capabilities), [contracts tour](/docs/tour/contracts) and [cassette guide](/docs/agents/cassettes) give executable examples of the recently landed APIs. ## Current scope and limitations [#current-scope-and-limitations] - `Http.recording`, `Llm.replay`, `Test.fixtures`, `Untrusted.validate` and `Html.from` are implemented. - Streaming HTTP (`Http.stream`, `Http.read_chunk`, `Body`, `Incoming`, design §17.88) remains planned; it is absent from these signatures. - `Sql.postgres` is not implemented. The source index records it as deferred past M4; SQLite and memory SQL cover the current examples. - Direct `Untrusted` SQL interpolation currently fails with `V2032`, despite the broader claim in the source index's deviations. Validate to a refined string first. - `Task.par_map` lives in `std/task`, not `List`. `Env.host()` takes no scope argument; use `Env.only` for attenuation. - JS `Int` arithmetic has a safe-integer range of ±(2^53−1); full-range i64 execution is planned for WASM. WASM and native execution are not CLI targets yet. - M3 still has [exit gates](/docs/roadmap). This signature inventory does not claim that M3, multi-package tooling or static verification is complete. ## Prelude [#prelude] In scope in every module without an import (design §9, with the additions marked +): | Kind | Names | |---|---| | Compiler-known types | `Unit Bool Int Float String Bytes Never List Map Set Range Handler Secret Untrusted` | | Std types | `Option Result` · + `Duration Instant Uuid Json Level` (prelude effects mention them; §15.1 and §15.4 use `Instant.format_iso`, `Level.Warn`, `Json.String` unimported) | | Constructors | `Some None Ok Err` (other variants are used qualified: `Level.Warn`, `Json.String(s)`) | | Effects | `Fail` (compiler-known) `Console Clock Random Env Log Task` · + `Test` | | Functions | `show` · + `expect expect_eq expect_fail expect_fails_with expect_defect expect_output expect_snapshot` (they need `Test`, which only `test`/`property` bodies have; elsewhere they are `V3001`) | | Tags (M3) | `sql html url` (`shell` is reserved by the prelude; no `std/shell` exists yet) | Not in the prelude, import them: `import std/retry.{Policy, retry}`, `import std/task.{Timeout, timeout}`, `import std/gen` (`gen.int(0, 9)`), `import std/graph.{Graph, NodeId}`, and the M3 modules. Home modules (design §4.9): `T.f(…)` and `x.f(…)` with `x: T` call `f` in the module that declares `T`; for compiler-known types it is `std/` (`List` → `std/list`). An effect's home module is the one declaring it, and `Eff.f(…)` calls a home-module function when `f` is not an operation (`Console.captured()`, `Clock.fixed(t)`, `Random.seeded(1)`). ## Signatures [#signatures] ### `std/core` [#stdcore] ```sakura fn show(a: A) -> String // @external type Violation = { type_name: String, clause: String, value_summary: String } type Trust ``` ### `std/unit` [#stdunit] ```sakura fn ignore(a: A) -> Unit ``` ### `std/option` [#stdoption] ```sakura type Option = None | Some(A) fn map(o: Option , f: fn(A) -> B ! e) -> Option ! e fn unwrap_or(o: Option , default: A) -> A fn or_fail(o: Option , err: E) -> A ! {Fail} fn expect (o: Option , msg: String) -> A // @external fn is_some (o: Option ) -> Bool // @total ``` ### `std/result` [#stdresult] ```sakura type Result = Ok(A) | Err(E) fn map(r: Result, f: fn(A) -> B ! e) -> Result ! e fn map_err(r: Result, f: fn(E) -> F) -> Result fn unwrap_or(r: Result, default: A) -> A fn raise(r: Result) -> A ! {Fail} fn is_ok(r: Result) -> Bool // @total fn is_err(r: Result) -> Bool // @total ``` ### `std/list` [#stdlist] ```sakura fn len (xs: List ) -> Int // @external, @total fn get (xs: List , i: Int) -> Option // @external, @total fn push (xs: List , x: A) -> List // @external fn slice (xs: List , start: Int, end: Int) -> List // @external fn empty () -> List fn concat (a: List , b: List ) -> List fn map(xs: List , f: fn(A) -> B ! e) -> List ! e fn filter(xs: List, f: fn(A) -> Bool ! e) -> List ! e fn filter_map(xs: List , f: fn(A) -> Option ! e) -> List ! e fn flat_map(xs: List, f: fn(A) -> List ! e) -> List ! e fn fold(xs: List, init: B, f: fn(B, A) -> B ! e) -> B ! e fn find(xs: List , f: fn(A) -> Bool ! e) -> Option ! e fn all(xs: List , f: fn(A) -> Bool ! e) -> Bool ! e // @total fn any(xs: List , f: fn(A) -> Bool ! e) -> Bool ! e // @total fn sort(xs: List ) -> List fn sort_by(xs: List , key: fn(A) -> K) -> List fn zip(a: List , b: List) -> List<(A, B)> fn enumerate(xs: List ) -> List<(Int, A)> fn reverse (xs: List ) -> List fn join(xs: List, sep: String) -> String fn sum(xs: List) -> Int fn first (xs: List ) -> Option // @total fn last (xs: List ) -> Option // @total fn contains(xs: List , x: A) -> Bool // @total fn unique(xs: List ) -> List fn range(start: Int, end: Int) -> List ``` ### `std/map` [#stdmap] ```sakura fn empty() -> Map // @external fn get(m: Map, k: K) -> Option // @external, @total fn insert(m: Map, k: K, v: V) -> Map // @external fn remove(m: Map, k: K) -> Map // @external fn len(m: Map) -> Int // @external, @total fn entries(m: Map) -> List<(K, V)> // @external fn of(pairs: List<(K, V)>) -> Map fn contains(m: Map, k: K) -> Bool // @total fn update(m: Map, k: K, f: fn(Option) -> V ! e) -> Map ! e fn keys(m: Map) -> List fn values(m: Map) -> List ``` ### `std/set` [#stdset] ```sakura fn empty() -> Set // @external fn insert(s: Set , x: A) -> Set // @external fn contains(s: Set , x: A) -> Bool // @external, @total fn len(s: Set ) -> Int // @external, @total fn to_list(s: Set ) -> List // @external fn of(xs: List ) -> Set ``` ### `std/string` [#stdstring] ```sakura error Utf8Error(offset: Int) fn len(s: String) -> Int // @external, @total fn chars(s: String) -> List // @external fn graphemes(s: String) -> List // @external fn split(s: String, sep: String) -> List // @external fn trim(s: String) -> String // @external fn starts_with(s: String, prefix: String) -> Bool // @external, @total fn ends_with(s: String, suffix: String) -> Bool // @external, @total fn contains(s: String, needle: String) -> Bool // @external, @total fn replace(s: String, from: String, to: String) -> String // @external fn to_lower(s: String) -> String // @external fn to_upper(s: String) -> String // @external fn parse_int(s: String) -> Option // @external fn parse_float(s: String) -> Option // @external fn to_bytes(s: String) -> Bytes // @external fn from_bytes(b: Bytes) -> Result // @external fn slice(s: String, start: Int, end: Int) -> String // @external fn repeat(s: String, n: Int) -> String requires n >= 0 fn pad_left(s: String, width: Int, fill: String) -> String requires len(fill) > 0 ``` ### `std/int` [#stdint] ```sakura fn to_float(i: Int) -> Float // @external fn to_string(i: Int) -> String // @external fn checked_add(a: Int, b: Int) -> Option // @external fn wrapping_add(a: Int, b: Int) -> Int // @external fn abs(i: Int) -> Int // @total fn min(a: Int, b: Int) -> Int // @total fn max(a: Int, b: Int) -> Int // @total fn clamp(i: Int, lo: Int, hi: Int) -> Int requires lo <= hi fn pow(base: Int, exp: Int) -> Int requires exp >= 0 ``` ### `std/float` [#stdfloat] ```sakura fn round(f: Float) -> Int // @external fn to_int_checked(f: Float) -> Option // @external fn sqrt(f: Float) -> Float // @external fn format(f: Float, decimals: Int) -> String requires decimals >= 0 // @external fn is_nan(f: Float) -> Bool ``` ### `std/bytes` [#stdbytes] ```sakura fn len(b: Bytes) -> Int // @external, @total fn get(b: Bytes, i: Int) -> Option // @external, @total fn from_list(xs: List) -> Bytes requires List.all(xs, fn(x) { x >= 0 && x <= 255 }) // @external ``` ### `std/duration` [#stdduration] ```sakura type Duration = Duration(Int) fn millis(n: Int) -> Duration fn seconds(n: Int) -> Duration fn minutes(n: Int) -> Duration fn to_millis(d: Duration) -> Int ``` ### `std/instant` [#stdinstant] ```sakura type Instant = Instant(Int) error TimeError(input: String) fn from_unix_millis(ms: Int) -> Instant fn to_unix_millis(i: Instant) -> Int fn add(i: Instant, d: Duration) -> Instant fn diff(a: Instant, b: Instant) -> Duration fn format_iso(i: Instant) -> String fn parse(text: String) -> Result ``` ### `std/uuid` [#stduuid] ```sakura opaque type Uuid = Uuid(String) error UuidError(input: String) fn to_string(u: Uuid) -> String fn parse(text: String) -> Result fn from_canonical(text: String) -> Uuid requires is_canonical(text) fn is_canonical(text: String) -> Bool // @total ``` ### `std/json` [#stdjson] ```sakura type Json = Null | Bool(Bool) | Number(Float) | String(String) | Array(List) | Object(Map) error DecodeError(path: String, message: String) fn encode(value: T) -> String // @external fn decode(text: String) -> Result // @external fn parse(text: String) -> Result // @external fn schema(witness: Option) -> Json // @external fn get(j: Json, key: String) -> Option fn get_string(j: Json, key: String) -> Option ``` ### `std/test` [#stdtest] ```sakura effect Test { fn record_failure(message: String) -> Unit fn failures() -> Int fn output(line: String) -> Unit fn output_lines() -> List fn snapshot(name: String, rendered: String) -> Unit fn fixtures() -> Dir } fn expect(cond: Bool) -> Unit ! {Test} fn expect_eq(actual: A, expected: A) -> Unit ! {Test} fn expect_fail(body: fn() -> T ! {Fail | e}, err: E) -> Unit ! {Test | e} fn expect_fails_with(body: fn() -> T ! {Fail | e}, pred: fn(E) -> Bool) -> Unit ! {Test | e} fn expect_defect(body: fn() -> T ! e) -> Unit ! {Test | e} // @external fn expect_output(lines: List) -> Unit ! {Test} fn expect_snapshot(name: String, value: A) -> Unit ! {Test} ``` ### `std/console` [#stdconsole] ```sakura effect Console { fn print(line: String) -> Unit fn read_line() -> Option } fn host() -> Handler // @external fn captured() -> Handler ``` ### `std/clock` [#stdclock] ```sakura effect Clock { fn now() -> Instant fn monotonic() -> Duration fn sleep(d: Duration) -> Unit } fn host() -> Handler // @external fn fixed(at: Instant) -> Handler fn virtual() -> Handler ``` ### `std/random` [#stdrandom] ```sakura effect Random { fn int(lo: Int, hi: Int) -> Int requires lo <= hi fn float() -> Float fn bytes(n: Int) -> Bytes requires n >= 0 fn uuid() -> Uuid } fn host() -> Handler // @external fn seeded(seed: Int) -> Handler ``` ### `std/env` [#stdenv] ```sakura effect Env { fn get(key: String) -> Option fn secret(key: String) -> Option> } fn host() -> Handler fn of(vars: Map) -> Handler fn only(keys: List) -> Handler ``` ### `std/log` [#stdlog] ```sakura type Level = Debug | Info | Warn | Error effect Log { fn event(level: Level, message: String, fields: List<(String, Json)>) -> Unit } fn stderr() -> Handler // @external fn host() -> Handler fn json() -> Handler // @external fn captured() -> Handler ``` ### `std/gen` [#stdgen] ```sakura type Gen = { sample: fn(Int) -> A ! {Random} } fn int(lo: Int, hi: Int) -> Gen requires lo <= hi fn bool() -> Gen fn one_of (choices: List ) -> Gen requires List.len(choices) > 0 fn list (item: Gen , max_len: Int) -> Gen> requires max_len >= 0 fn string(max_len: Int) -> Gen requires max_len >= 0 fn map(g: Gen , f: fn(A) -> B) -> Gen fn pair(a: Gen, b: Gen) -> Gen<(A, B)> fn for_all(g: Gen, runs: Int, prop: fn(A) -> Unit ! {Test | e}) -> Unit ! {Random, Test | e} ``` ### `std/retry` [#stdretry] ```sakura type Policy = { retry_on: fn(E) -> Bool, max_attempts: Int, backoff: Duration, jitter: Bool, deadline: Option } fn policy(retry_on: fn(E) -> Bool, max_attempts: Int) -> Policy requires max_attempts >= 1 fn retry(p: Policy, action: fn() -> T ! {Fail | e}) -> T ! {Clock, Random, Fail | e} ``` ### `std/task` [#stdtask] ```sakura type Scope type Fiber effect Task { fn scope(body: fn(Scope) -> T ! e) -> T ! e fn spawn(s: Scope, body: fn() -> T ! e) -> Fiber ! e fn join(f: Fiber) -> T fn all(bodies: List T ! e>) -> List ! e fn race(bodies: List T ! e>) -> T ! e fn yield_now() -> Unit } fn host() -> Handler // @external fn deterministic(seed: Int) -> Handler // @external error Timeout(limit: Duration) fn timeout(limit: Duration, action: fn() -> T ! e) -> T ! {Clock, Task, Fail | e} fn par_map(xs: List , f: fn(A) -> B ! e) -> List ! {Task | e} ``` ### `std/graph` [#stdgraph] ```sakura type NodeId = NodeId(Int) type Graph = { nodes: Map, edges: Map>, next: Int } fn empty() -> Graph fn insert(g: Graph, n: N) -> (Graph, NodeId) fn get(g: Graph, id: NodeId) -> Option // @total fn connect(g: Graph, a: NodeId, b: NodeId) -> Graph requires get(g, a).is_some() && get(g, b).is_some() fn neighbors(g: Graph, id: NodeId) -> List fn len(g: Graph) -> Int ``` ### `std/untrusted` [#stduntrusted] ```sakura fn of(value: T) -> Untrusted // @external fn validate(u: Untrusted) -> Result // @external, compiler-known (§17.71) fn trust(u: Untrusted, reason: Trust) -> T fn check(u: Untrusted, clause: String, pred: fn(T) -> Bool) -> Result fn len(u: Untrusted) -> Int ``` ### `std/secret` [#stdsecret] ```sakura fn of(value: T) -> Secret // @external fn expose(s: Secret, reason: Trust) -> T fn map(s: Secret, f: fn(T) -> U) -> Secret ``` ### `std/decimal` [#stddecimal] ```sakura opaque type Decimal = { whole: Int, frac: List } error DecimalError(input: String) fn from_int(n: Int) -> Decimal fn zero() -> Decimal fn parse(text: String) -> Result fn to_string(d: Decimal) -> String fn add(a: Decimal, b: Decimal) -> Decimal fn sub(a: Decimal, b: Decimal) -> Decimal fn neg(a: Decimal) -> Decimal fn mul(a: Decimal, b: Decimal) -> Decimal fn div_checked(a: Decimal, b: Decimal, places: Int) -> Option requires places >= 0 fn round(d: Decimal, places: Int) -> Decimal requires places >= 0 ``` ### `std/path` [#stdpath] ```sakura type Path = String where is_relative(it) fn is_relative(s: String) -> Bool // @total fn of(s: String) -> Path requires is_relative(s) fn join(p: Path, rest: String) -> Path requires is_relative(rest) fn to_string(p: Path) -> String ``` ### `std/fs` [#stdfs] ```sakura type Dir type Entry = { name: String, is_dir: Bool } type Mode = Read | Write | Append opaque type File = { id: Int, path: Path, mode: Mode } // @resource (§17.70) error FsError(path: String, reason: String) effect Fs { fn root() -> Dir fn read(path: Path) -> Bytes ! {Fail} fn read_text(path: Path) -> Untrusted ! {Fail} fn write(path: Path, data: Bytes) -> Unit ! {Fail} fn list(dir: Path) -> List ! {Fail} fn exists(path: Path) -> Bool fn with_file(path: Path, mode: Mode, body: fn(File) -> T ! e) -> T ! {Fail | e} fn read_chunk(file: File, max: Int) -> Bytes ! {Fail} requires max > 0 fn write_chunk(file: File, data: Bytes) -> Unit ! {Fail} } fn host() -> Handler fn rooted(dir: Dir) -> Handler fn subdir(d: Dir, name: String) -> Dir ! {Fail} fn memory(files: List<(Path, Bytes)>) -> Handler fn read_all(file: File) -> Bytes ! {Fs, Fail} ``` ### `std/cli` [#stdcli] ```sakura effect Cli { fn args() -> List fn exit(code: Int) -> Never requires code >= 0 && code <= 255 } error CliError(message: String) fn host() -> Handler fn of(args: List) -> Handler fn parse(args: List) -> T ! {Fail} // @external ``` ### `std/url` [#stdurl] ```sakura type Url = String where is_valid(it) fn is_valid(s: String) -> Bool // @total fn host(u: Url) -> Option fn path(u: Url) -> String fn query_param(u: Url, name: String) -> Option fn template(parts: List, args: List) -> Url fn encode_component(s: String) -> String ``` ### `std/request` [#stdrequest] ```sakura type Method = Get | Head | Post | Put | Patch | Delete type Request = { method: Method, url: Url, headers: List<(String, String)>, body: String, secret_headers: List<(String, Secret)>, params: List<(String, String)> } error BadRequest(detail: String) fn of(method: Method, url: Url) -> Request fn post(path: String, body: String) -> Request fn post_json(url: Url, body: T) -> Request fn json(req: Request, limit: Int) -> T ! {Fail} fn param(req: Request, name: String) -> Option fn header(req: Request, name: String) -> Option ``` ### `std/response` [#stdresponse] ```sakura type Status = Int where it >= 100 && it <= 599 type Response = { status: Status, headers: List<(String, String)>, body: String } error HttpError(status: Option, reason: String) fn status(code: Int, body: String) -> Response requires code >= 100 && code <= 599 fn ok_json(value: T) -> Response fn html(h: Html) -> Response fn json(r: Response, limit: Int) -> T ! {Fail} fn text(r: Response, limit: Int) -> Untrusted ! {Fail} ``` ### `std/http` [#stdhttp] ```sakura type Matcher = Any | Path(String) | Method(Method) error RateLimited(retry_after: Option) effect Http { fn send(req: Request) -> Response ! {Fail} } fn get(url: Url) -> Response ! {Http, Fail} fn post_json(url: Url, body: T) -> Response ! {Http, Fail} fn bearer(req: Request, token: Secret) -> Request fn host() -> Handler fn scoped(hosts: List) -> Handler fn recording(path: Path) -> Handler fn scripted(script: List<(Matcher, Response)>) -> Handler ``` ### `std/html` [#stdhtml] ```sakura opaque type Html = Html(String) fn text(s: String) -> Html fn untrusted(u: Untrusted) -> Html fn raw(markup: String, reason: Trust) -> Html fn from(v: T) -> Html // each non-`Html` html"…" value goes through it (§17.77) fn concat(parts: List) -> Html fn to_string(h: Html) -> String fn template(parts: List, args: List) -> Html ``` ### `std/router` [#stdrouter] ```sakura opaque type Router = { routes: List> } fn new() -> Router fn route(r: Router, method: Method, pattern: String, h: fn(Request) -> Response ! e) -> Router fn get(r: Router, pattern: String, h: fn(Request) -> Response ! e) -> Router fn post(r: Router, pattern: String, h: fn(Request) -> Response ! e) -> Router fn put(r: Router, pattern: String, h: fn(Request) -> Response ! e) -> Router fn delete(r: Router, pattern: String, h: fn(Request) -> Response ! e) -> Router fn handle(r: Router, req: Request) -> Response ! e ``` ### `std/serve` [#stdserve] ```sakura type Address = { host: String, port: Int } error ServeError(reason: String) effect Serve { fn serve(handle: fn(Request) -> Response ! e, addr: Address) -> Never ! {Fail | e} } fn listen(router: Router, addr: Address) -> Never ! {Serve, Fail | e} fn of(host: String, port: Int) -> Address requires port >= 0 && port <= 65_535 fn host() -> Handler fn scripted(requests: List) -> Handler ``` ### `std/budget` [#stdbudget] ```sakura type Limits = { tokens: Option, usd: Option, calls: Option } type Cost = { tokens: Int, usd: Float, calls: Int } type Reservation = { estimate: Cost } type BudgetKind = Tokens | Usd | Calls error BudgetExceeded(kind: BudgetKind) effect Budget { fn reserve(est: Cost) -> Reservation ! {Fail} fn settle(r: Reservation, actual: Cost) -> Unit } fn limits(l: Limits) -> Handler fn unlimited() -> Handler fn zero() -> Cost ``` ### `std/prompt` [#stdprompt] ```sakura type PromptPart = Text(String) | Untrusted(Untrusted) | Image(Bytes) opaque type Prompt = Prompt(List) fn of(parts: List) -> Prompt fn text(s: String) -> Prompt fn parts(p: Prompt) -> List ``` ### `std/llm` [#stdllm] ```sakura type Model = Model(String) type Request = { system: String, user: Prompt, model: Model, max_tokens: Int, temperature: Float } error Refused error InvalidOutput(violations: List) error Truncated error ProviderError(status: Int) type LlmError = Refused | InvalidOutput | Truncated | RateLimited | Timeout | ProviderError | BudgetExceeded type ToolSpec = { name: String, description: String, schema: Json } type ToolCall = { id: String, name: String, input: Json } type ToolResult = { id: String, output: Json } type Turn = Asked(List) | Answered(List) type Step = Answer(T) | Use(List) type Partial = { text: String, step: Int, calls: List } effect Llm { fn generate(req: Request) -> T ! {Fail} fn generate_text(req: Request) -> Untrusted ! {Fail} fn stream(req: Request, on_partial: fn(Partial) -> Unit ! e) -> T ! {Fail | e} fn step(req: Request, tools: List, transcript: List) -> Step ! {Fail} } fn request(system: String, user: Prompt) -> Request fn of(name: String) -> Model fn default() -> Model fn anthropic(key: Secret, model: Model) -> Handler // @external fn replay(path: Path) -> Handler fn scripted(responses: List) -> Handler ``` ### `std/tool` [#stdtool] ```sakura opaque type Tool = { spec: ToolSpec, run: fn(Json) -> Json ! {Fail | e} } error ToolError(tool: String, tag: String, payload: Json) fn from(name: String, description: String, f: fn(A) -> R ! {Fail | e}) -> Tool fn name(t: Tool) -> String fn spec(t: Tool) -> ToolSpec fn call(t: Tool, input: Json) -> Json ! {Fail | e} ``` ### `std/agent` [#stdagent] ```sakura type Agent = { request: Request, tools: List>, max_steps: Int, stop: fn(Partial) -> Bool } fn run(a: Agent) -> T ! {Budget, Llm, Fail | e} requires a.max_steps > 0 ``` ### `std/sql` [#stdsql] ```sakura type SqlValue = Null | Int(Int) | Float(Float) | Text(String) | Blob(Bytes) opaque type Query = { text: String, params: List } error SqlError(message: String) effect Sql { fn query(q: Query) -> List ! {Fail} fn execute(q: Query) -> Int ! {Fail} fn transaction(body: fn() -> T ! {Sql | e}) -> T ! {Fail | e} } fn from(value: T) -> SqlValue // each sql"…" value goes through it (§4.11) fn template(parts: List, args: List) -> Query fn migrate(statements: List>) -> Unit ! {Sql, Fail} fn sqlite(path: Path) -> Handler // @external fn memory() -> Handler // @external ```