wtf platform

Why

A program that calls setTimeout, crypto, fetch or process.env directly is tied to the place it runs. To test it, you patch globals and hope that nothing else reads them.

With @wtf/platform, your program takes a Platform as a parameter instead: its timers, crypto, console, locks, channels, workers, fetch, file system, environment, paths, folders, terminal, a way to open a URL and, where the platform has one, a way to start a process. Your code never reads a global. A test gives it doubles, and gets the same result every time.

import type { Platform } from '@wtf/platform'
import { testPlatform } from '@wtf/platform/test'
import { sleep } from '@wtf/platform/timers'

const program = async ({ platform, signal }: { platform: Platform; signal: AbortSignal }) => {
  platform.console.log('Running on %s', platform.dirs.os)
  await sleep(1000, platform, signal)
}

// In a test, time moves only when you say so.
const platform = testPlatform()
const running = program({ platform, signal: new AbortController().signal })
await platform.timers.advance(1000)
await running
platform.console.records // each line it logged

A platform for each place

Where your program runs	Its platform
Node	nodePlatform({ fetch, storage }), or runMain(program, { fetch, storage })
A page	browserPlatform({ window })
A test	testPlatform(), with fake timers and a seeded crypto
A dry run	memoryPlatform(), with each process answered by your script

Where a web standard defines a member, the platform uses the standard’s own name and signature: setTimeout, performance, crypto, console, navigator.locks, navigator.storage, BroadcastChannel, MessageChannel, Worker and fetch. So a browser’s window and Node’s own objects fit as they are. Where no standard exists, the platform adds its own members: env, path, dirs, terminal and open.

The packages

@wtf/platformThe Platform type, the helpers, such as sleep, randomId and exec, and a test double for each member.

@wtf/platform-nodeNode's platform, built from Node's own modules, with spawn, and runMain to run a program.

@wtf/platform-browserA page's platform, built from the window you pass in, and the environment a page carries.

@wtf/platform-memoryA platform in memory, for a test or a dry run: your script answers each process, and the platform records it.

The file system

The file system is the browser’s own file system API, the WHATWG File System Standard. Your code takes a folder handle and works with any handle it gets. A browser gives you one already. The fs packages give you one anywhere else, and helpers that work on any of them.

@wtf/platform-fsFind a file by its path, match paths by a glob, and read and write a platform's files on any folder handle.

@wtf/platform-fs-nodeA folder handle on Node's disk, and the storage that Node's platform takes.

@wtf/platform-fs-memoryA folder handle in memory, for a test or a dry run.

@wtf/platform-fs-adapterFolder handles on any file system shaped like the fs/promises of Node: Bun's, Deno's or memfs.

What you get

No globals

No package reads globalThis. Each helper asks only for the members it uses, so you can pass the whole platform or only those members.

A double for each member

Fake timers, a seeded crypto, a console that records, a fetch that your handler answers, and processes that your script answers.

Held to the standards

The Web Platform Tests run against the doubles and against Node’s own objects, so each one behaves as its standard says, errors included.

Errors you can match

A member that no standard defines throws a PlatformError. A member from a web standard throws what the standard says, a DOMException.

Learn more

Getting startedWhat a platform holds, how to get one in Node, in a page and in a test, how to start a process, and what errors to expect.

The environmentRead environment variables as a value you pass around, combine them, and parse them into typed settings.

Files and foldersGet a folder handle wherever your code runs, read and write its files, and reach a platform's files by their paths.

API referenceEvery package, module and member, at the version that you install.