Standard Library

The standard library is written in Polar and lives in the repository's std/ folder. Import a module with uses Std.<Name>, then call its functions through the module name.

Signatures use the notation from the main concepts: lowercase names are type variables, / {…} lists effects, {| e} passes effects through, and where asks for a trait.

List

List<a> = Nil | Cons(a, List<a>) derive(Eq, Show)

Write lists with [1, 2, 3] rather than Cons. List syntax needs uses Std.List.

Option

Option<a> = None | Some(a) derive(Eq, Show)

Result

Result<e, a> = Err(e) | Ok(a) derive(Eq, Show)

Map

Map<k, v> = Empty | Entry(k, v, Map<k, v>)

Keys are compared with Eq. Every change returns a new map.

Json

traits
  Json<a> {
    to_json(value: a) -> JsonValue
    from_json(value: JsonValue, path: String) -> Result<JsonError, a>
  }

types
  JsonValue =
    | JNull
    | JBool(Bool)
    | JNumber(Float)
    | JString(String)
    | JArray(List<JsonValue>)
    | JObject(List<{ key: String, value: JsonValue }>)

  JsonError = { path: String, expected: String, found: String }

Derive Json for your own types. Int, Float, String, Bool, List, Option and Result implement it already. See Working with JSON.

For writing a Json implementation by hand, the module also exports object, tagged, object_fields, field, variant and unknown_variant. They're the building blocks derive(Json) uses.

Ref

Ref<a>

A mutable cell. See Mutable State.

Table

Table<r> = Ref<{ next: Int, rows: List<{ id: Int, row: r }> }>

An in-memory table with automatic numeric ids.

Id

Id<a> = Id(Int)

A typed id. An Id<Post> and an Id<User> are different types, so you can't pass one where the other is expected. Id implements Eq, Show and Json.

Http

Header = { name: String, value: String }

Request = {
  method: String,
  path: String,
  query: String,
  headers: List<Header>,
  body: String,
}

Response = { status: Int, headers: List<Header>, body: String }

Url

Pair = { name: String, value: String } derive(Eq, Show)

Dom

Provides the Browser host and the Dom effect. See Running in the Browser.

effects
  Dom in Browser {
    append_text(tag: String, text: String) -> {}
    append_html(html: String) -> {}
    has(id: String) -> Bool
    set_html(id: String, html: String) -> {}
  }

Process

Provides the Node host and the Process effect. See Command-Line Programs.

types
  EnvVar = { name: String, value: String }

  RunOptions = { cwd: Option<String>, env: List<EnvVar> }

  Output = { code: Int, stdout: String, stderr: String }

effects
  Process in Node {
    args() -> List<String>
    env(name: String) -> Option<String>
    cwd() -> String
    set_exit_code(code: Int) -> {}
    run(command: String, args: List<String>, options: RunOptions) -> Int
    output(command: String, args: List<String>, options: RunOptions) -> Output
  }

Fs

Reads and writes text files on the Node host. See Command-Line Programs.

types
  FsError = { code: String, path: String, message: String } derive(Show)

effects
  Fs in Node {
    read(path: String) -> Result<FsError, String>
    write(path: String, text: String) -> Result<FsError, {}>
    append(path: String, text: String) -> Result<FsError, {}>
    exists(path: String) -> Bool
    is_dir(path: String) -> Bool
    mkdir_all(path: String) -> Result<FsError, {}>
    list(path: String) -> Result<FsError, List<String>>
    walk(path: String) -> Result<FsError, List<String>>
    remove(path: String) -> Result<FsError, {}>
    remove_all(path: String) -> Result<FsError, {}>
  }

An FsError's code is Node's: ENOENT, EEXIST, ENOTDIR, EACCES and so on, so you can match on it.

Path

Pure functions on POSIX paths, written in Polar. They don't touch the file system and work on every host.

Regex

Regular expressions, using the host's JavaScript syntax with the u flag and no other flags. Matching is unanchored, so write ^…$ to match the whole text. It works on both Node and Browser. A pattern with catastrophic backtracking, like (a+)+$, hangs as it does in JavaScript. Regex has Eq and Show, shown as /pattern/.

types
  Regex = Regex(String)

Time

An instant in UTC, held as milliseconds since the Unix epoch, and the Clock effect that reads it. Clock works on both Node and Browser. A program can bind it itself, to pin the time in a test. Time has Eq, Show and Json: its JSON form is an ISO-8601 string like "2026-10-02T09:30:00.123Z".

types
  Time = Time(Int)

effects
  Clock {
    now() -> Time
  }

Crypto

Hashing, signing and random tokens over node:crypto. Crypto works on Node only, so a Browser build can't use Random. Randomness is the Random effect, so a function that makes a token says so in its type, and a program can bind Random to a fixed value in a test. There is no Bytes type: random bytes are a hex string.

effects
  Random {
    bytes(count: Int) -> String
  }

Assert

Failed = Failed(String)

Math

Prelude

Always in scope, without a uses.

traits
  Eq<a> {
    eq(x: a, y: a) -> Bool
  }

  Show<a> {
    show(value: a) -> String
  }

Int, Float, String and Bool implement both. == uses Eq, and #{…} uses Show.