Docs/Tools

Ecosystem packages

Databases, caches, and file formats as packages.

On this page

These official packages cover what the standard library leaves out: databases, caches, tokens and file formats. Install one with vman and import it by name:

Terminal
vman install github.com/ctxcode/valk-redis
Valk
use redis

vman install adds the dependency to valk.json and copies it into vendor/. vpkg.dev lists every package with its versions and the lowest compiler version each needs. See Projects & packages for how dependencies work.

Databases#

Package What it is
valk-sql One API over all drivers: query builder, migrations, pooling, rows read into your classes
valk-sqlite SQLite, bound to the C library; the database is a file
valk-postgres PostgreSQL, written in Valk, with prepared and cached statements
valk-mysql MySQL, written in Valk

Each driver works on its own and also plugs into valk-sql. Install both:

Terminal
vman install github.com/ctxcode/valk-sql
vman install github.com/ctxcode/valk-sqlite
Valk
use sql
use sqlite

let db = sqlite.database(sqlite.open("app.db") ! panic("%{E.message}"))
defer db.close()

// Always `?` placeholders; Postgres gets $1, $2 on the way out
db.exec("INSERT INTO users (name, age) VALUES (?, ?)", .{ sql.Value.of("Ada"), sql.Value.of_int(36) }) ! panic("%{E.message}")

let rows = sql.Query.select()
    .on(db)
    .from("users")
    .where("age > ?", .{ sql.Value.of_int(18) })
    .all() ! panic("%{E.message}")

Switching databases means changing the line that opens it; valk-sql handles the differences in placeholders, RETURNING, LIMIT/OFFSET and insert ids.

Caches and queues#

valk-redis talks to Redis and Valkey, with pipelines, transactions, scripts, pub/sub, streams, TLS, pools and Sentinel:

Valk
use redis

let con = redis.connect("127.0.0.1", 6379) ! panic("%{E.message}")
defer con.close()

con.set("greeting", "hello", 60) ! panic("%{E.message}")    // expires after 60 seconds
let visits = con.incr("visits") ! panic("%{E.message}")
let job = con.blpop("jobs", 5) ! panic("%{E.message}")      // waits up to 5 seconds

Web services#

Package What it is
valk-jwt JSON Web Tokens: HS256, HS384 and HS512
valk-uuid UUIDs: random (v4), time-ordered (v7) and name based (v5, v3)
Valk
use jwt
use uuid

let id = uuid.v7()                  // sorts by creation time
let token = jwt.encode_of(Session { sub: id.to_string() }, secret, jwt.Algorithm.hs256, 3600)
let session = jwt.decode_to[Session](token, secret) ! panic("%{E.message}")

The algorithm comes from the caller, never from the token, so a token claiming alg: none is refused.

File formats#

Package What it is
valk-toml TOML 1.0, decoded into your classes or a json.Value, and encoded back
valk-image PNG, JPEG, WebP and BMP: read, write, resize, crop, flip and rotate
Valk
use toml
use valk.fs

let settings = toml.decode_to[Settings](fs.read("config.toml") !!) ! panic("%{E.message} at line %{E.line}")

Command line apps#

valk-cli parses commands, options and arguments, writes the help text, and prints completion scripts for bash, zsh and fish:

Valk
use cli

fn main(args: Array[String]) {
    let app = cli.App.new("greet", "Greet someone", "1.0.0")
    app.root.flag("loud", "l", "Greet in capitals")
    app.root.argument("name", "Who to greet", true)
    app.root.on_run(fn(ctx: cli.Context) i32 !cli.Error {
        let line = "Hello " + ctx.arg("name") + "!"
        println(ctx.flag("loud") ? line.upper() : line)
        return 0
    })
    exit(app.run(args))
}

Example project#

valk-starter-api is a small JSON API built from these parts: valk.http for the server, valk-sql with valk-sqlite for storage and migrations, valk-redis for rate limiting, and valk-jwt with valk-uuid for sessions. Read it as a reference; it is not a package to install.