fjs/types is the standard library's data layer: the values every other part of the repository is built from, and the functions over them. It is the most imported directory in the tree — the compiler, the effects layer, RTTI, the media formats and the website all reach for result, list, nullable and function before anything else.
Every module.f.* here is plain FunctionalScript. A value is never mutated, functions are curried with the configuration first and the data last, and nothing performs I/O. The one exception is result/module.mjs, a host JavaScript companion whose tryCatch and asyncTryCatch run a callback that may throw. Most calls take one argument each, but not all: fixpoint(step, same)(start) takes two in its first call. Most directories hold a module.f.mjs (or module.f.js), its types.ts, and a proof.f.mjs whose exported proof is the module's test suite.
These hold across the directory, and knowing them makes every module below easier to read.
- Absence is
null. A lookup that finds nothing answersnull, neverundefined(nullable). A JavaScript API that answersundefinedis converted at the boundary withfromUndefined. - Failure is a value. A step that can fail answers a
Result:['ok', value]or['error', e]. Throwing is kept for broken invariants, not for input a caller could get wrong. - Sequences are lazy lists. A
Listmay be an array, anull, a cons cell, a concatenation of two lists or a thunk, and every combinator accepts all five. Most combinators that answer a list, such asmaporfilter, do their work only when something reads the result. A few read the whole input when called, so they never return on an infinite list: those that answer a single value, such asfoldandlength, andreverse, which answers a list but has to reach the end first. - Functions take their configuration first.
map(f)(list),at(key)(object),okThen(step)(result): the argument that varies least comes first, so a partially applied function is a reusable value. - Order is deterministic. Collections that a
Mapor an object would keep in insertion order (ordered_map,string_set,sorted_set) keep sorted order instead, so two equal collections built differently serialise the same way.
| If you need to… | Read |
|---|---|
| return a value or an error | result |
| handle a value that may be absent | nullable |
| walk, transform or build a sequence | list |
| compose, flip or iterate functions | function |
| read an object's own property safely | object |
| take apart a fixed or non-empty array | array |
| keep a sorted, persistent map or set | btree and its users |
| work with arbitrary-precision integers or bits | bigint, bit_vec |
| Module | What it is |
|---|---|
result | Result<T, E>: success or failure as a tagged tuple, with okThen, mapOk and okList. |
nullable | Nullable<T> (T | null): match, map, fromUndefined, unwrap. |
option | Option<T>, a value as a zero- or one-element tuple. Types only. |
list | List<T>, the lazy sequence, and about forty combinators over it. |
function | compose, identity, flip, iterate, fixpoint; operator, compare and length below it. |
array | Readonly arrays: safe at, first, last, splitFirst, splitLast, dedup, assoc. |
object | Plain objects: own-property at, fromEntries, sort, isObject, structurallySame. |
string | join, concat, repeat, cmp, splitAt and occurrences over strings and string lists. |
number | sum, min, max, cmp, countOnes, isByte; is_negative_zero below it. |
range | A closed numeric interval [a, b] with contains and one. |
version | Dotted version numbers such as 26.1.0, parsed and compared by their numbers. |
| Module | What it is |
|---|---|
nominal | Branded types that the type checker will neither mix nor order-compare with another. |
phantom | Phantom<S, T>, a type parameter with no runtime field, like Rust's PhantomData. |
ts | The Equal compile-time check, used with Assert from asserts, and a printer that writes TypeScript type text. |
| Module | What it is |
|---|---|
btree | The persistent 2-3 B-tree that ordered_map and string_set are built on. |
ordered_map | A string-keyed map, traversed in key order. |
string_set | A set of strings, traversed in order. |
set | A persistent set with Set's equality (objects by identity) and a logarithmic add. |
map | mapSet and mapDelete: copy-on-write updates of a JavaScript Map. |
sorted_list | Merging, intersecting and searching sorted lists. |
sorted_set | A set held as a sorted array: union, intersect, has. |
range_set | A set of numbers as half-open boundaries, closed under union, intersection and complement. |
range_map | A map from numeric ranges to values, with a merge for overlapping ranges. |
bit_set | The bitmask-as-set algebra, shared by the two below. |
byte_set | A set of bytes (0..255) in one 256-bit bigint. |
nibble_set | A set of nibbles (0..15) in one 16-bit number. |
patricia_trie | A streaming Patricia trie that builds content-addressed binary trees. |
stack_walk | A driver for walking deep input on an explicit stack instead of the call stack. |
| Module | What it is |
|---|---|
bigint | bigint utilities: log2, bitLength, abs, sign, factorial, divUp and more. |
bigfloat | Decimal-to-binary float conversion on bigint mantissas and exponents. |
prime_field | Arithmetic modulo a prime: inverse, power and square root. The base of crypto/secp. |
bit_vec | Bit vectors as bigints with a stop bit, and their conversions to and from bytes. |
uint8array | Conversions between Uint8Array and bit vectors. Deprecated in favour of bit_vec. |
fjs/rttidescribes these same values at runtime: an RTTI schema can check that a parsed value really is aResultor a list of strings.fjs/effectsis the layer above: a value that performs operations, built fromResultandList.doc/DESIGN.mdholds the principles these conventions come from.