Guides on this site are the repository READMEs; the API reference is generated from the sources. AI agents: npx skills add mirek/prelude or see the prelude skill.

prelude monorepo

A pnpm workspace containing small, focused TypeScript utility packages published under the @prelude/* scope.

What this repository contains

This repository is organized as a monorepo. Every directory under packages/* is a workspace package with its own package.json; pnpm manifests:check fails on a directory without one, because the build, typecheck and pack scripts discover packages by manifest and would otherwise skip it silently.

• Shared workspace configuration at the root (pnpm-workspace.yaml, root package.json).
• Individual package source, tests, and package-level docs in each packages/<name> directory.

Quick start

Prerequisites

• Node.js 22 or later (see Supported runtimes)
• pnpm 11.1.3 through the root packageManager declaration

Install dependencies

pnpm install --frozen-lockfile

Run the CI-equivalent quality gate

pnpm verify

pnpm verify runs the same checks as GitHub Actions, in this order:

1. pnpm manifests:check — verifies normalized package manifests, exports, and workspace TypeScript configs.
2. pnpm release-hooks:check — rejects package-local version, push, or publish hooks.
3. pnpm makefiles:check — rejects package recipes that build with tsc directly or use unquoted recursive globs.
4. pnpm docs:check — verifies package READMEs, license references, manifest descriptions and the package index below.
5. pnpm test:check — rejects unseeded randomness and unsupported node:test timeout arguments in the default suite.
6. pnpm lint — type-aware linting across packages.
7. pnpm typecheck — checks every package library and test TypeScript project independently.
8. pnpm test — runs all colocated *.test.ts files through Node's test runner.
9. pnpm test:scripts — runs the tests of the repository scripts themselves.
10. pnpm build — rebuilds every package with a tsconfig.lib.json from clean source.
11. pnpm pack:check — packs every public package and installs the tarballs into an isolated consumer project.

Release a change

Every pull request adds a changeset (pnpm changeset, or pnpm changeset --empty when nothing publishable changed); CI rejects pull requests without one. Merged changesets accumulate in an automated chore(release): version packages pull request; merging it bumps versions and changelogs, and the Publish workflow then publishes every not-yet-published version to npm with provenance and tags it <package>@<version>. See .changeset/README.md.

Concurrency tests use explicit barriers, fake schedulers, and awaited task settlement rather than random sleeps or eventual polling. Optional randomized stress coverage must use a reproducible seed.

The data structures with the largest state spaces (rb-tree and its Bag/Map, radix-trie, range-set, sorted-array, set, channel, serial-queue) also have model-based property tests (packages/*/src/model.test.ts, laws.test.ts) built on the private @prelude/testing package: checkTrace generates operation traces from a seed, replays them against the structure and a naive reference model with every invariant checked after each step, and on failure shrinks the trace and reports seed, trial and the minimal operation sequence. The default suite runs a bounded number of trials; SLOW_TESTS=<factor> multiplies them, which the weekly Stress workflow (.github/workflows/stress.yml, also runnable by hand) does with a factor of 20.

The package check verifies declared entry points, declaration resolution, root and subpath runtime imports, workspace dependency rewriting, the externally published TypeScript configs, and exclusion of development-only files. Isomorphic packages are additionally imported with Node's platform globals removed and every Node builtin unresolvable, and their declarations are type-checked without @types/node. Every publishable library also builds from source during its own prepack lifecycle.

GitHub Actions runs these checks independently on Node.js 22 (the supported floor), 24 and 26. The aggregate CI job is suitable as the required branch-protection check.

Supported runtimes

Every published @prelude/* package declares "engines": { "node": ">=22" }; the root manifest declares the same. Node 22 is the oldest release line still in maintenance, and CI runs the full quality gate on it and on the current release lines, so the floor is exercised, not inferred.

• Compile target. @prelude/tsconfig/base.json sets target: ES2024 and lib: ["ES2024", "ES2025.Iterator", "ES2025.Collection"]: the ES2024 language and library plus the ES2025 iterator helpers and Set methods, all of which Node 22 ships. Symbol.dispose/Symbol.asyncDispose (also in Node 22) are declared by isomorphic.d.ts rather than by the ESNext.Disposable lib, because that lib would also expose DisposableStack, AsyncDisposableStack and SuppressedError, which are Node 24+. Backend and test projects see those (and Float16Array) anyway through @types/node's own lib references, so .oxlintrc.json bans them with no-restricted-globals. Nothing newer (Promise.try, RegExp.escape, ...) is visible to the compiler, so it cannot enter a package by accident. Widening the list is a support-policy change: it requires the feature to be available in the oldest supported Node and an entry in this section.
• Node types. The workspace type-checks against @types/node for the oldest supported release, so backend packages cannot use a Node API added after the floor.
• Package classes. A package is isomorphic when its tsconfig.lib.json extends @prelude/tsconfig/isomorphic.json (compiled with types: [], so no Node global or node: module resolves) or Node-only when it extends backend.json. Currently Node-only: @prelude/assert, @prelude/fs, @prelude/log, @prelude/progress, @prelude/rb-tree, @prelude/refute, @prelude/repl (and the private @prelude/json); every other package is isomorphic and is expected to run in browsers, workers and edge runtimes that support ES2024. pnpm pack:check enforces both classes on every CI Node version.
• TypeScript. @prelude/tsconfig declares typescript >=6 as a peer dependency: its lib entries use the ES2025.* names TypeScript 6 introduced (5.x only knows them as ESNext.*). Package declarations are emitted and consumer-checked (pack:check) with the workspace TypeScript version; older compilers are not tested.
• Dropping a runtime. Raising the floor is a breaking change for every package: bump the engines constant in scripts/normalize-package-manifests.mjs, the CI matrix, @types/node and this section together, and release the affected packages with a major bump.

Clean TypeScript build artifacts

make clean

Cancellation

Long-lived asynchronous operations across the packages share one cancellation convention, built on the platform's AbortSignal:

• An operation that can wait accepts an optional signal (usually in a trailing options object: sleep(ms, { signal }), channel.read({ signal }), map(f, { concurrency, signal }), select({ signal }, ...attempts)).
• A signal that is already aborted makes the operation reject (or the generator throw) at once, before it touches anything.
• Aborting a pending operation removes its listeners, clears its timers, withdraws its pending reads/writes/queue entries and rejects it with signal.reason — the same value everywhere; no package wraps or replaces it. AbortController.abort() without a reason yields the platform's AbortError DOMException.
• Once an operation has settled it detaches from the signal, so aborting later is a no-op and never produces an unhandled rejection.
• Work that is already in flight in user code (a mapping function, a retry attempt, a queue task, f in timeout) is not interrupted — JavaScript cannot interrupt it — but the operation does not wait for it: it rejects at once and the work's eventual result is dropped (a late rejection is swallowed, never left unhandled). Pass the same signal into that work when it should stop too. consume is the exception: it awaits callbacks already in flight before rejecting, as it does on failure.
• Consumers that want a graceful stop rather than an error use the iterator protocol (break out of for await, return()), which closes upstream resources; a signal is for stopping from the outside.

Packages following the convention: function (sleep, timeout, eventually, throttle), emitter (eventually, eventuallyIf), channel (read, maybeRead, write, maybeWrite, writeIgnore, select/selectNext/selectAsync, after, ofIterable, ofAsyncIterable), serial-queue (pushWith), progress (start, also disposable), remote-clock (midSeconds, midSecondsInterval), async-generator (sleep, jitter, ofInterval, map, tap, consume), plus actor/remote-actor (ask) and jsonrpc (call) which already did. Operations without a signal are either instantaneous or already have an explicit stop (Emitter.on returns an unregister function, throttle returns a function whose pending call the signal drops, serial-queue.rejectAll empties a queue).

Package index

Generated from the workspace manifests by pnpm docs:write; pnpm docs:check fails when it drifts.

Package documentation

Every package ships Readme.md and License.md (CC0-1.0). pnpm docs:check (part of pnpm verify) enforces the shared shape:

• a top-level heading and a specific description in package.json (no Foo module. placeholders — the description is what npm and the index above show);
• an install command (npm i -E @prelude/<name>) and an import example;
• a # License section that points at ./License.md;
• no machine-local paths, badges for retired services, links to the retired standalone repositories, or license text that contradicts the manifest;
• relative links that resolve.

A minimal package README therefore looks like:

# Foo module

One or two sentences on what the package is for and when to reach for it.

# Usage

    npm i -E @prelude/foo

    import * as Foo from '@prelude/foo'
    Foo.bar(1)

# License

This package is dedicated to the public domain under [CC0 1.0](./License.md).

Package manifests get repository, homepage, bugs, files, exports and types from pnpm manifests:write, derived from the package directory, so they cannot drift from the repository layout.

Documentation site and AI agents

The documentation site at https://mirekrusin.com/prelude/ is built by pnpm site:build (scripts/build-site.mjs) from the Markdown already in this repository — this README, every packages/*/Readme.md and CHANGELOG.md — plus a TypeDoc API reference under /api/, and is deployed by the Pages workflow on every push to main. Nothing on the site is written twice: package pages are the package READMEs.

For language models the site also publishes:

• /llms.txt — an index of the guides, the API reference and the skill; /llms-full.txt is every guide in one file.
• /.well-known/agent-skills/index.json — the agent-skills discovery index, with the SHA-256 digest of the skill file.
• /.well-known/agent-skills/prelude/SKILL.md — the prelude skill: which @prelude/* package to reach for, how they compose, conventions and common mistakes. Its source is skills/prelude/SKILL.md (the workspace's .claude/skills/prelude links to it) and the build copies it verbatim.

Install the skill into an agent (Claude Code, Codex, Cursor and others supported by skills):

npx skills add mirek/prelude

The well-known index is published under the site's base path (/prelude/.well-known/agent-skills/index.json); origin-root discovery (npx skills add https://<domain>) needs the site on its own domain — set SITE_URL accordingly in the Pages workflow, nothing else changes.

pnpm site:preview builds the site without the API reference (a few seconds instead of a minute) into site/, which is ignored by git.

License

The repository root is licensed under CC0-1.0. Individual packages may declare their own licenses in package-level files/manifests.