Library reference
Every module a Nish program can import, one page each, generated from the doc comments of its source. The builtins come with the compiler; the nish/ modules are the standard library, written in Nish and grouped here by area. The language specification, the compiler's own command line and diagnostics, and the configuration files it reads are references too.
Language specification
The normative rules: what the compiler accepts and what it means.
Builtins
The globals and the 11 nish: modules that come with the compiler.
Core
Numbers, bytes, array loops, sorting, randomness, dates and times, and the test runner: 9 modules.
Collections
Map, Set and the operations JavaScript lacks on them: 2 modules.
Text
Strings, regular expressions, JSON and YAML: 14 modules.
Terminal and CLI
Terminal output and input, a step's input with no terminal, and command-line parsing: 9 modules.
Graphics and sound
Drawing into a frame of pixels and making short sounds: 2 modules.
Concurrency
Threads, locks, shared memory and queues between processes or a wasm page: 6 modules.
Data
SQLite and compression: 5 modules.
Networking
DNS, HTTP/1.1, HTTP/2, HTTP/3, QUIC, TLS and the server: 55 modules.
Cryptography
Hashes, ciphers, signatures, certificates and passwords: 21 modules.
Command line
Every command, flag and exit code of nish.
Diagnostics
Every diagnostic code, what it means and a program that provokes it.
Configuration files
Every field Nish reads in package.json, and the capability lockfile it writes.
Builtins
| Module | |
|---|---|
| Globals | Ambient declarations for the Nish global surface. |
nish:async |
Tasks for async functions: start one and go on, or await two to eight at once. |
nish:compact |
The marker interfaces that pick a class's layout (WP48). |
nish:fs |
Files and directories: read, write, rename, remove and list paths on the host's file system. |
nish:io |
Text and bytes to stdout and stderr with nothing added, and the panic that ends a program on an unmet invariant. |
nish:net |
Non-blocking sockets for a program that owns its loop: TCP, UDP, Unix-domain sockets, and a level-triggered readiness loop to wait on them. |
nish:process |
The process and its host: exit, the environment, children, signals, the clocks, scheduling, and the size of the machine. |
nish:region |
Memory a program frees when it says so: an arena of its own, reached through a handle, so that what lives and dies together goes back with one free where the thread's arena would hold it until the program ends. |
nish:secret |
Key material as an opaque value that the checker keeps from leaving the program by any road but one, and that is zeroed, with a store no optimiser may remove, before the function that made it lets go of it. |
nish:simd |
Sixteen-byte vectors of one lane type, and the lane-wise operations on them, each lowered to target-independent LLVM vector IR. |
nish:term |
Terminal input for a full-screen program: read a key the moment it is pressed, wait for one with a timeout that doubles as a frame clock, and ask the terminal whether it is one, how big it is, and to stop echoing. |
nish:unsafe |
Element access with no bounds check, signed arithmetic that wraps, a C string or struct read through a pointer nothing proves, and the errno a C call left. |
Standard library
Core
| Module | |
|---|---|
nish/array |
The array methods that take a callback, and slice, in Nish: each a plain loop, compiled once per callback. |
nish/base64 |
Standard base64 (RFC 4648 §4) with = padding, the encoding kitty graphics frames are sent in. |
nish/bytes |
Fixed-width integers and doubles read from, and written into, a byte array at an offset, in either byte order. |
nish/math |
Math.atan2, Math.tan and Math.hypot on f64, and on a freestanding wasm build Math.sin, Math.cos, Math.exp, Math.log, Math.pow and the % of two f64s, in Nish rather than libm, so a program answers the same on every target and the optimiser sees the whole function. |
nish/pair |
Two values answered by one call. |
nish/random |
A seeded generator of pseudo-random numbers whose every answer is the same natively and under Node. |
nish/sort |
xs.sort(cmp) on an array, in Nish: a stable merge sort, compiled once per comparator. |
nish/temporal |
Dates, times, instants and durations in the ISO 8601 calendar, under the names and the rules of TC39's Temporal (docs/wp64-temporal.md). |
nish/testing |
A test runner for Nish programs, written in Nish. |
Collections
| Module | |
|---|---|
nish/collections |
The global Map and Set (docs/wp32-map.md). |
nish/map |
Two operations on the global Map that JavaScript's does not have, written so that a program using them still runs unmodified under Node (docs/wp32-map.md §9.2). |
Text
| Module | |
|---|---|
nish/json-equal |
Whether two JSON values are equal by JSON Schema's rule, a canonical text and a hash that agree with it, and the first repeated element of an array, which is what const, enum and uniqueItems ask. |
nish/json-format |
The string formats of JSON Schema draft 2020-12 (§7.3 of the validation vocabulary), each a predicate, and one dispatcher that answers valid, invalid or unknown for a format named in a schema. |
nish/json-number |
JSON number text compared and divided exactly, the arithmetic JSON Schema's minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, const and enum ask for. |
nish/json-pointer |
RFC 6901 JSON Pointers: parsed into their tokens, escaped, resolved against a JsonDocument, and checked, with JSON Schema's relative JSON Pointer beside them. |
nish/json-tokenizer |
A validating, streaming tokenizer for RFC 8259 JSON held in a window of a u8[]. |
nish/json-typed |
Decode a JSON object into a class, and encode a class back, with code the compiler writes from the class's fields. |
nish/json-value |
Any JSON document as a tree a program can read, build and write back, with every number kept as the text it was written in. |
nish/json |
The value of a field, or of several, of one flat JSON object; and JsonWriter, which writes any JSON value into a byte buffer. |
nish/regex |
Regular expressions whose search time is linear in the input, whatever the pattern. |
nish/text |
The string operations a program has to write itself. |
nish/yaml-json |
One YAML document loaded into a JsonDocument, with every value's and key's source range, so that one validator and one YamlLineIndex serve a JSON text and a YAML text alike: |
nish/yaml-lines |
Byte offsets turned into the line:column a person reads. |
nish/yaml-write |
A JSON value written as YAML text that parseYaml reads back as the same tree. |
nish/yaml |
A YAML 1.2 parser that keeps where everything came from. |
Terminal and CLI
| Module | |
|---|---|
nish/cli-args |
A command tree for a large command-line tool: declared once with a builder, parsed in one walk over the arguments, and answered as the matched command's id and every value with where it came from. |
nish/cli-flags |
A command line's flags, declared once as data and read back by name, with the same declaration writing the --help rows. |
nish/cli |
A command-line tool's help menu: whether a stream gets colour, the escapes that paint it, and the rows a --help is made of. |
nish/input |
What one fixed step of a program reads from its player: the key and mouse events since the last step, and which keys are held down. |
nish/term-io |
Opening a terminal, drawing frames, reading events and leaving it as it was: the one entry point that uses the other term modules and does the I/O. |
nish/term-pixels |
A framebuffer of pixels, and the encoders that draw it to a terminal with the best backend the terminal has: kitty graphics, Sixel, half-block cells or ASCII. |
nish/term-probe |
What the terminal a program runs in can do (its colours, keyboard protocol, graphics and size), asked of it once at start and read from its answer. |
nish/term-rate |
How fast the link to the terminal is, measured from frames sent and acknowledged, and the frame rate and drawing detail a program keeps to under it. |
nish/term |
A terminal drawn as a grid of coloured cells, and the keys a terminal sends turned into events. |
Graphics and sound
| Module | |
|---|---|
nish/raster |
Software drawing into a frame of 0xRRGGBB pixels: colour arithmetic, rectangles, anti-aliased discs, additive glows, a vertical gradient, a 5×7 pixel font, and two fixed pools that move and draw themselves (a particle pool and a trail). |
nish/synth |
Short sounds made from nothing: square, triangle and noise voices with a pitch slide and a decaying envelope, mixed into an array of f64 samples. |
Concurrency
| Module | |
|---|---|
nish/host/game |
The memory a game built for wasm32 shares with the page that runs it: the frame it draws, the input the page feeds it, the sounds it asks for and the samples the page plays them from. |
nish/host/ring |
A single-producer, single-consumer ring of i32 words over module storage, shared by a wasm module and the page that drives it (docs/wp50-wasm-host.md §11). |
nish/host/text |
Text in module storage, for a wasm module and the page that drives it (docs/wp50-wasm-host.md §7). |
nish/sync/ring |
Bounded lock-free queues of byte records in a shared region, for handing work between processes on different cores. |
nish/sync/shm |
Memory that several processes map at once, and the atomics that order what they write to it. |
nish/threads |
Data parallelism, a scope for heterogeneous tasks, and a lock that owns its data (docs/wp29-thread-surface.md §4.1, §4.2 and §4.3). |
Data
| Module | |
|---|---|
nish/compress/checksum |
The two checksums the compressed formats carry: CRC-32 (ISO 3309, the polynomial gzip's trailer uses, RFC 1952 §8) and Adler-32 (zlib's trailer, RFC 1950 §9). |
nish/compress/deflate |
DEFLATE (RFC 1951), both ways, in pure Nish: a compressor with levels and a decompressor that refuses malformed input with an error code. |
nish/compress/gzip |
The gzip file format (RFC 1952) around nish/compress/deflate: a ten-byte header, the DEFLATE stream, and a trailer of the CRC-32 and the length of the data mod 2^32. |
nish/compress/zlib |
The zlib format (RFC 1950) around nish/compress/deflate: a two-byte header, the DEFLATE stream and the Adler-32 of the data, big-endian. |
nish/sqlite |
nish/sqlite (the file std/sqlite.ts) — SQLite, the database in a file, from a Nish program. |
Networking
| Module | |
|---|---|
nish/net/buffer-pool |
Fixed-size byte buffers a server's connections borrow and give back, so the memory a server holds follows the connections that are moving bytes, not the slots it was sized for. |
nish/net/dns-config |
/etc/resolv.conf and /etc/hosts, read from bytes the caller already has into fixed tables. |
nish/net/dns-message |
A DNS query for one A or AAAA question written into the caller's buffer, and the reply to it read back into addresses. |
nish/net/dns-resolver |
A DNS stub resolver with no I/O of its own: it says which bytes to send to which server, reads the bytes that came back, and answers each lookup's addresses, while the program's own loop owns the sockets and the clock. |
nish/net/dns |
The stub resolver of nish/net/dns-resolver driven over nish:net sockets on the caller's own readiness loop, and resolveHost, which runs a loop of its own for a program that has none. |
nish/net/fetch |
An HTTP/1.1 client. |
nish/net/handler |
Complete requests and their responses over the HTTP/1.1 carrier, so that a server answers requests instead of driving Http1Server's events by hand. |
nish/net/hpack |
HPACK, the header compression of HTTP/2, as RFC 7541 defines it: the §5.1 integer with an N-bit prefix, the §5.2 string literal with Appendix B's Huffman code, the Appendix A static table, the §2.3.2 dynamic table with its §4 size accounting and eviction, and the four §6 representations. |
nish/net/http-compress |
Content coding for HTTP responses (RFC 9110 §8.4 and §12.5.3): reading a request's Accept-Encoding and compressing a body with Content-Encoding: gzip, for any of the three servers. |
nish/net/http-fields |
The header model HTTP/2 and HTTP/3 share: what a field name and a field value may hold, the pseudo-header fields and the order and count they come in, the connection-specific fields neither version carries, and the shapes of a request, a response and a trailer section. |
nish/net/http-server |
One handler for HTTP/1.1, HTTP/2 (over TLS and cleartext) and HTTP/3, with Alt-Svc advertising the HTTP/3 port. |
nish/net/http1-client-codec |
The client side of HTTP/1.1, sans-IO: a request writer and an incremental response parser, bytes in, events and bytes out, and no socket anywhere. |
nish/net/http1-codec |
An incremental HTTP/1.1 request parser and a response writer, sans-IO: bytes in, events and bytes out, and no socket anywhere. |
nish/net/http1-server |
The server side of HTTP/1.1 (RFC 9112): a sans-IO connection that drives nish/net/http1-codec's parser, and two pools of them for a program that owns its readiness loop, one on nish:net's plain TCP and one on nish/net/tls-tcp with ALPN http/1.1. |
nish/net/http2-cleartext |
HTTP/2 over plain TCP with prior knowledge (h2c, RFC 9113 §3.3): a pool of Http2Connections, one per accepted socket, for a program that owns its readiness loop. |
nish/net/http2-frame |
The frames of HTTP/2 (RFC 9113 §4 and §6): the nine-byte header, every one of the ten frame types read and written, and the size, flag, padding and stream-identifier rules each one carries. |
nish/net/http2-tls |
HTTP/2 over TLS 1.3 on TCP: a pool of Http2Connections, one beside each slot of a TlsTcpServer, for a program that owns its readiness loop. |
nish/net/http2 |
The server side of an HTTP/2 connection (RFC 9113): the connection preface, SETTINGS and their acknowledgement, the stream state machine of §5.1, flow control on the connection and on every stream with WINDOW_UPDATE, PING, RST_STREAM, GOAWAY with the last stream identifier, header blocks across CONTINUATION frames decoded by nish/net/hpack, and extended CONNECT (RFC 8441). |
nish/net/http3-frame |
The frames and stream types of HTTP/3 (RFC 9114 §6.2, §7): frame headers, SETTINGS, the one-identifier frames (GOAWAY, MAX_PUSH_ID, CANCEL_PUSH), and which types are HTTP/2's reserved ones or unknown. |
nish/net/http3-server |
HTTP/3 over QUIC on one UDP socket: a pool of slots, each a reusable QuicConnection with an Http3Connection beside it, a QuicListener in front for the datagrams no slot owns, for a program that owns its readiness loop. |
nish/net/http3 |
The server side of an HTTP/3 connection (RFC 9114) on the streams of a QuicConnection (nish/net/quic): the control stream and SETTINGS both ways, the QPACK encoder and decoder streams (opened, at dynamic table capacity 0), requests and responses on bidirectional streams with their bodies streamed both ways, GOAWAY, and RFC 9114's error codes. |
nish/net/oidc |
Verify a JWT from an OpenID Connect issuer: find the issuer's keys through discovery (OpenID Connect Discovery 1.0), read its JWK Set (RFC 7517, RFC 7518 §6, RFC 8037), follow its key rotation, and check a token's signature and claims with nish/crypto/jwt. |
nish/net/outbound |
The policy for a program that fetches URLs it did not choose: a webhook sender, a link previewer, an importer that takes a URL from a form. |
nish/net/postgres-async |
PgAsyncPool, PostgreSQL connections an async task awaits a query on, so a task's query waits on its socket while the executor runs the others. |
nish/net/postgres-carrier |
PgCarrier, a PgPool's queries on an HttpHandler's loop, so a route handler queries PostgreSQL without blocking its worker. |
nish/net/postgres |
The client side of PostgreSQL's frontend/backend protocol, version 3.0: a sans-IO connection that writes the frontend's messages into an output buffer and reads the backend's from an input buffer, for a program that owns its socket (nish:net) and its loop. |
nish/net/prefork |
Run a server on every core: a supervisor process that starts one worker process per core, restarts one that dies, and stops them all on SIGTERM or SIGINT (docs/wp42-multicore-server.md §2.3). |
nish/net/qpack |
QPACK, the field compression of HTTP/3, as RFC 9204 defines it with a dynamic table of capacity 0: the Appendix A static table, the §4.1.1 prefixed integer up to 62 bits, the §4.1.2 string literal with an N-bit prefix, the §4.5 field-line representations under a Required Insert Count of 0, and what the encoder and decoder streams of §4.2 may carry when neither side ever inserts. |
nish/net/quic-conn-ack |
The packet numbers one QUIC packet number space has received, kept as ranges, which is what duplicate detection reads (RFC 9000 §12.3) and what an ACK frame is written from (§13.2, §19.3). |
nish/net/quic-conn-cid |
A QUIC connection's connection-ID table (RFC 9000 §5.1): the IDs this endpoint issued, which a datagram is routed by, and the ones the peer issued, which this endpoint sends to. |
nish/net/quic-conn-params |
QUIC's transport parameters (RFC 9000 §18), the bytes each endpoint carries in TLS's quic_transport_parameters extension (RFC 9001 §8.2), encoded and parsed. |
nish/net/quic-datagram |
A fixed ring of QUIC DATAGRAM payloads (RFC 9221), one each way per connection: what the application queued to send, waiting for room in a packet and in the congestion window, and what the peer sent, waiting for the application to read it. |
nish/net/quic-frame |
The frames of QUIC version 1 (RFC 9000 §19) and RFC 9221's DATAGRAM, read from a decrypted packet payload and written into one, and the transport error codes a connection closes with (§20.1). |
nish/net/quic-listener |
What a QUIC version 1 server answers to a datagram no connection owns: Version Negotiation for a version it does not speak (RFC 9000 §6, §17.2.1), a Retry that asks a client to prove its address before any connection state exists (§8.1.2, §17.2.5), and a stateless reset for a packet sent to a connection the server no longer has (§10.3). |
nish/net/quic-packet |
QUIC version 1's packets, as RFC 9000 §16-§17 frames them and RFC 9001 §5 protects them: the variable-length integer, the long and short headers, packet-number encoding and recovery, the Initial secrets, AEAD packet protection, header protection and the Retry integrity tag. |
nish/net/quic-recovery |
QUIC loss detection and congestion control (RFC 9002): the packets each packet number space has in flight, the round-trip estimate, loss by packet and by time threshold, the probe timeout with its backoff, NewReno or CUBIC, and a pacer. |
nish/net/quic-stream |
The streams of one QUIC version 1 connection (RFC 9000 §2-§4): stream IDs and their four types, the sending and receiving state machines, reassembly, flow control per stream and for the connection, and the stream limits. |
nish/net/quic |
The server side of a QUIC version 1 connection (RFC 9000, RFC 9001, RFC 9221): the TLS 1.3 handshake carried in CRYPTO frames at three encryption levels, transport parameters both ways, acknowledgements per packet number space, the connection-ID table, streams both ways (nish/net/quic-stream) and DATAGRAM frames once the handshake is done. |
nish/net/router |
A method and path router for HTTP servers, independent of the carrier: the same table answers an HTTP/1 request line and an HTTP/2 or HTTP/3 :path. |
nish/net/serve |
An HTTP/1.1 server for an async program: one task and one region per request, answers in request order. |
nish/net/tls-tcp |
TLS 1.3 over TCP (WP34 T2): a pool of server connections on nish:net, each a TlsRecordServer driving a TlsServer, for a program that owns its readiness loop; and TlsTcpClient, one client connection that authenticates the server (nish/net/tls/verify) and is driven by the same kind of loop or, through tlsConnect, readWait and writeAll, by none (its own comment, below, says how). |
nish/net/tls |
The server side of a TLS 1.3 handshake (RFC 8446), from the client's first ClientHello to its Finished, carrier-agnostic and sans-IO. |
nish/net/tls/client |
The client side of a TLS 1.3 handshake (RFC 8446), from its ClientHello to its Finished, carrier-agnostic and sans-IO: the mirror of nish/net/tls's TlsServer. |
nish/net/tls/codec |
The TLS 1.3 handshake messages a server and a client read and write (RFC 8446 §4), as bytes. |
nish/net/tls/record-client |
A TLS 1.3 client over a byte stream: the record layer of nish/net/tls/record wrapped around nish/net/tls/client's TlsClient, sans-IO. |
nish/net/tls/record-server |
A TLS 1.3 server over a byte stream: the record layer of nish/net/tls/record wrapped around nish/net/tls's TlsServer, sans-IO. |
nish/net/tls/record |
The TLS 1.3 record layer (RFC 8446 §5): the framing of a byte stream into records, the protection of one direction of it under a traffic secret, and the next secret a KeyUpdate moves to. |
nish/net/tls/schedule |
The TLS 1.3 key schedule and transcript hash (RFC 8446 §4.4.1, §7.1, §7.3) for the three cipher suites nish/net/tls negotiates. |
nish/net/tls/ticket |
TLS 1.3 session tickets a server seals for itself (RFC 8446 §4.6.1), and the strike register that makes each one single-use (§8.1). |
nish/net/tls/verify |
The TLS client's one authentication seam: whether the server a TlsRecordClient reached is the one its serverName says, decided at TLS_RECORD_AUTH and handed to the connection as its verdict. |
nish/net/upstream |
Outbound HTTP/1.1 calls from a route handler that never block its worker: a pool of keep-alive connections to one origin, registered on the HttpHandler's own poll loop and read through the nish/net/http1-client-codec codec. |
nish/net/url |
The request target's path and query, split and percent-decoded in place, and its query string read as key/value pairs; and whole URLs, parsed into their parts and references resolved against them. |
nish/net/websocket |
RFC 6455 WebSocket framing and both sides of the opening handshake, sans-IO: bytes in, events and bytes out. |
nish/net/webtransport |
WebTransport over HTTP/3, server side, as draft-ietf-webtrans-http3-02 has it and as Chrome and the wtransport 0.7 crate negotiate it: sessions made by an extended CONNECT (RFC 9220) with :protocol webtransport, HTTP datagrams (RFC 9297) carrying the session's quarter stream ID, the session's unidirectional and bidirectional streams, and CLOSE_WEBTRANSPORT_SESSION and DRAIN_WEBTRANSPORT_SESSION on the CONNECT stream's capsules. |
nish/release |
What the newest release of a project on GitHub is, whether it is newer than the one running, and a small cache so a program asks at most once a day. |
Cryptography
| Module | |
|---|---|
nish/crypto/aes |
AES-128 and AES-256 (FIPS 197), GCM on top of them (NIST SP 800-38D), and QUIC's AES header-protection mask (RFC 9001 §5.4.3). |
nish/crypto/base64url |
RFC 4648 §5 base64url, unpadded, as JWS and the relay's grants spell a key or a tag inside a URL or a header. |
nish/crypto/bcrypt-batch |
A login batcher: it queues bcrypt verifies and hashes as they arrive, sends them as bcryptVerifyN / bcryptHashN batches, and runs the batches on std/threads tasks, one per core. |
nish/crypto/bcrypt |
Bcrypt password hashing, $2b$ out and $2a$, $2b$, $2y$ in. |
nish/crypto/chacha20poly1305 |
The ChaCha20 stream cipher, the Poly1305 one-time authenticator and the AEAD built from the two, as RFC 8439 defines them, plus the ChaCha20 header-protection mask of RFC 9001 §5.4.4. |
nish/crypto/ct |
Comparing secrets without telling the clock where they differ. |
nish/crypto/ed25519 |
The Ed25519 signature scheme of RFC 8032 (§5.1). |
nish/crypto/hkdf |
HKDF as RFC 5869 defines it, over HMAC-SHA-256 and HMAC-SHA-384. |
nish/crypto/hmac |
HMAC as RFC 2104 defines it, over SHA-256, SHA-384 and SHA-512. |
nish/crypto/jwt |
JSON Web Tokens in the JWS compact serialization: verify one and check its claims, or sign one. |
nish/crypto/p256 |
ECDSA over NIST P-256 (secp256r1), with the deterministic nonces of RFC 6979. |
nish/crypto/p384 |
ECDSA signature verification over NIST P-384 (secp384r1). |
nish/crypto/pki-roots |
The root certificates a program should trust, read from where OpenSSL and Go look for them: the files SSL_CERT_FILE and SSL_CERT_DIR name, or else the system's bundle. |
nish/crypto/pki |
Whether the certificate chain a TLS server sent leads to a root the program trusts and names the host it dialled: RFC 5280 §6 path validation and RFC 6125 §6 hostname matching, at the instant the caller gives. |
nish/crypto/rsa |
RSA signature verification: RSASSA-PKCS1-v1_5 and RSASSA-PSS over SHA-256, SHA-384 and SHA-512, under a public key read from its DER. |
nish/crypto/sha1 |
SHA-1 as FIPS 180-4 §6.1 defines it, in pure Nish. |
nish/crypto/sha256 |
SHA-256 as FIPS 180-4 §6.2 defines it, in pure Nish. |
nish/crypto/sha512 |
SHA-512 and SHA-384, written from FIPS 180-4. |
nish/crypto/x25519 |
The X25519 Diffie-Hellman function of RFC 7748. |
nish/crypto/x509-random |
The private key and the serial number nish/crypto/x509's x509MintSelfSigned needs, drawn from the operating system's CSPRNG, and the mint that draws its own serial. |
nish/crypto/x509 |
DER, PEM and the X.509 certificates a WebTransport or TLS server holds: read a P-256 private key and a certificate chain out of PEM, and mint the short-lived self-signed ECDSA P-256 certificate a browser pins by its SHA-256. |

