The Velt standard library#

The standard library is written in Velt and ships with the toolchain. A module is imported as velt/<module>, the path of its folder in the standard library:

import { readFile, writeFile } from "velt/fs";
import { Deque } from "velt/collections";

await writeFile("notes.txt", "hello");
const queue = new Deque<string>();
queue.pushBack(await readFile("notes.txt"));
console.log(queue.length);

The prelude (strings, arrays, Map, Math, JSON, Error, promises, …) is in scope everywhere without an import, and so are Node's web globals: fetch, Request, Response, Headers, Blob, File, FormData, AbortController, AbortSignal, URL, URLSearchParams, Set, RegExp, Symbol, TextEncoder, TextDecoder, btoa, atob, DOMException, structuredClone, ArrayBuffer, DataView, Uint8Array and the other typed arrays, and ReadableStream. velt doc --std generates HTML API documentation from the sources; the API pages here are generated the same way.

Importing a module#

• An area or a module is a folder, and its import path is that folder: velt/fs, velt/net, velt/net/http, velt/encoding/json. Each has one public API, the names its index.vlt exports. The other files of a module are its internals, and importing one is an error that names the module to import instead:

  tsdoes not compile

  import { Deque } from "velt/collections/deque";

  Text

  error: `velt/collections/deque` is internal to `velt/collections`
    = note: import what you need from "velt/collections", the module's public API

• The prelude is never imported. Its names are in scope in every module; import … from "velt/prelude" is an error. The same goes for velt/lang/…, which implements the language: what a program uses of it is global (Symbol, Proxy, Uint8Array, …) or syntax (import.meta).

Conventions#

• Errors are thrown classes extending the prelude Error { message }. Catch them with try { … } catch (e) { e.message }; e is the union of the error classes the calls can throw, narrowed with instanceof. Each module has its own error class (UrlError, CsvError, …). Messages start with a capital letter (Invalid URL: …); IoError messages are lowercase, as in Node (ENOENT: no such file or directory, open 'x', handle is closed). An error that escapes the program prints Uncaught <Class>: <message> at <file>:<line>:<col>, naming the error's actual class and, for an error thrown inside the standard library, the line of your code that called it.
• I/O errors are IoError { code, message } from velt/io. code is a Node-style name: "ENOENT", "EACCES", "ECONNREFUSED", "EOF", … A failed file-system call has Node's message: ENOENT: no such file or directory, open 'data.txt'.
• Strings are sequences of UTF-16 code units, as in JS: lengths and positions (slice, indexOf, regex match offsets, CSV and CLI column widths) count code units. Their text is stored and written as UTF-8; Buffer.byteLength(s) is that size.
• Async functions return promises that start at once, like JS (a direct await costs nothing). A promise that is neither awaited nor spawned is a compile error. *Sync variants block the calling thread.
• Handles: some modules return handle structs (TcpStream, FileReader, ChildProcess, …) that you can pass around and capture freely and release with close() (closing again does nothing). Planned: they become disposable classes with using support.

Modules#

Each module has a page at the same path as its import (velt/net/http is /docs/std/net/http/); a module with several parts has a page for each below its own. The catalog groups them by what they are for.

The prelude's globals have pages of their own too: Symbol and typed arrays, ArrayBuffer and DataView.

Packages, not std#

The standard library is the core every program can count on. Servers and database drivers are libraries, so they are packages, written on public std APIs only: http-server (serve, with web-standard Request and Response handlers), sqlite, postgres and redis. A program imports a package by its name (import { serve } from "http-server") once package.vlt lists it in dependencies. std keeps what any of them builds on: fetch and the web types, velt/net/http/h2, velt/db, velt/dev, velt/native and the WebSocket client.

Runtime-backed and pure modules#

Every module is Velt source. Some bind runtime functions (velt_rt_*, implemented in Rust) for what Velt can't do on its own:

Pure Velt: velt/path, velt/mem, velt/collections, velt/encoding (with velt/encoding/csv and velt/encoding/json), velt/cli, velt/jsx, velt/generate, velt/net/http/h2, velt/net/url and the timers of velt/time (built on sleep, spawn and velt/task signals); some use only the runtime's UTF-8 conversions and error-code names.

WebAssembly#

On the WebAssembly targets the language and the pure modules work as on native targets, and velt/fs uses the WASI file system. TCP, child processes and the native code of the database packages are not available; fetch links but rejects with IoError ENOTSUP (no network) (WebAssembly).