Eutaxy

eutaxy/cloudflare ​

import { … } from "eutaxy/cloudflare"; 45 functions and values, 37 types; each links to the file that declares it.

Functions, classes and values ​

atLeastOnce ​

function atLeastOnce(name: string, effect: EffectSelector, key: string, expected: readonly JsonValue[]): AtLeastOnce

Every value in expected appears at least once as key in a selected effect: nothing was lost. Source

atLeastOncePerMessage ​

function atLeastOncePerMessage(name: string, drive: Drive, effect: EffectSelector, key: string, bodyKey: string): AtLeastOnce

Every message's (or request's, or call's) bodyKey value must appear at least once as key in a selected effect: nothing the drive delivered may be lost. Source

atMostOncePerKey ​

function atMostOncePerKey(name: string, effect: EffectSelector, key: string): AtMostOncePerKey

No two selected effects share the value at key (a dot path into the effect's payload): nothing happened twice for one key, a payment recorded twice, a message sent twice. Source

callee ​

function callee(binding: string, worker: { readonly entry: string; readonly config: string; readonly entrypoint?: string }): CalleeSetup

Run the Worker behind a service binding for real, named by its module and its wrangler config, relative to the scenario; entrypoint names the export the binding reaches. Source

calleeEnv ​

function calleeEnv(name: string, env: object, aliases: Readonly<Record<string, string>> = {}): object

The callee's env: the scenario's env seen under the callee's own names, each mapped onto <name>/<key>. Source

check ​

function check(spec: ScenarioSpec, platform: Platform, options: ExploreOptions = { seed: spec.name }): Promise<ScenarioVerdict>

Explore a scenario on a platform and return its verdict. Source

checkInWorkerd ​

function checkInWorkerd(input: WorkerdCheckInput): Promise<CheckTransport>

Run the scenario's check, with its specs observed, and return what the CLI reads back. Source

cloudflareRegressionTest ​

function cloudflareRegressionTest(verdict: Violated, options: CloudflareRegressionOptions): string

A Vitest regression test for a Cloudflare scenario, to run under the Cloudflare Vitest plugin. Source

createCloudflarePlatform ​

function createCloudflarePlatform(options: CloudflarePlatformOptions): Platform

The Cloudflare platform for check, run inside workerd under the Cloudflare Vitest plugin: the scenario's drive delivered to the Worker's handlers, its bindings proxied so every call is an effect that faults can hit, and the setup's resources reset before each run and snapshotted after it. Source

cron ​

function cron(expression: string, options: CronOptions = {}): CronDrive

Drive the Worker's scheduled() handler with the ticks of a Cron Trigger expression, in Cloudflare's dialect: one tick by default, re-run 0 times by default. Source

d1Param ​

function d1Param(index: number): string

Dot path to the Nth bound parameter of a D1 statement, in an effect payload. Source

d1Read ​

function d1Read(binding: string, op: "first" | "all" | "raw" = "first"): EffectSelector

Reads of a D1 binding: first (result payload { row }), all or raw. Source

d1Rows ​

function d1Rows(binding: string, table: string, where?: readonly RowCondition[]): StateQuery

Rows of a D1 table in the end-of-run snapshot, optionally filtered. Source

d1Schema ​

function d1Schema(binding: string, schemaFile: string): D1Setup

A D1 binding the scenario uses: its tables dropped before each run and the schema file applied, relative to the scenario. Source

d1Write ​

function d1Write(binding: string, op: "run" | "batch" = "run"): EffectSelector

Effect conventions for D1 (what the proxies record): call payload { args: { sql, params } } result payload { args: { sql, params }, result: { changes, lastRowId } } A committed write is a result whose result.changes is at least 1. Source

defineScenario ​

function defineScenario(input: CloudflareScenarioInput): ScenarioSpec

Build and validate a scenario spec; throws with every problem listed. Source

durableObject ​

function durableObject(binding: string, objects: { readonly [name: string]: { readonly [key: string]: JsonValue } } = {}, options: { readonly alarmsPerObject?: number; readonly sql?: { readonly [name: string]: DurableObjectSqlSeed }; } = {}): DurableObjectSetup

A Durable Object namespace the scenario uses: cleared before each run, the named objects seeded with key-value entries (and with sql, a SQLite-backed object's tables and rows), and its storage snapshotted after the run. Source

durableObjectRows ​

function durableObjectRows(binding: string, object: string, where?: readonly RowCondition[]): StateQuery

The storage of one object (by the name its id was made from) as rows { key, value }, for state invariants. Source

durableObjectTable ​

function durableObjectTable(binding: string, object: string, table: string, where?: readonly RowCondition[]): StateQuery

One SQL table of a SQLite-backed object (by the name its id was made from) at the end of the run, its rows as the table holds them, for state invariants. Source

everyRow ​

function everyRow(name: string, query: StateQuery, holds: readonly RowCondition[]): EveryRow

Every row the query selects satisfies all conditions. Source

expectHolds ​

function expectHolds(spec: ScenarioSpec, platform: Platform, options?: ExploreOptions): Promise<void>

For use from a test: passes only when the scenario is BOUNDED. Source

external ​

function external(name: string, host: string, options: { readonly dedupeBy?: string; readonly responses?: readonly ScriptedResponse[] } = {}): ExternalDecl

Declare an external service: requests to host are answered from responses (every request gets 200 and an empty body when omitted), and dedupeBy names the header whose value makes repeated requests idempotent at that service. Source

fetchCall ​

function fetchCall(externalName: string, method?: string): EffectSelector

Selects the requests to an external that took effect: a request replayed under a dedupe key the external had already seen is not counted. Source

http ​

function http(requests: readonly HttpRequestInput[], options: HttpCallerOptions = {}): HttpDrive

Drive the Worker's fetch() handler with these requests, each resent as options say. Source

httpResponse ​

function httpResponse(path: string, options: { readonly ok?: boolean } = {}): EffectSelector

Selects the responses the Worker returned for a path (ok narrows to 2xx or to everything else). Source

implies ​

function implies(name: string, when: EffectSelector, key: string, state: StateQuery, column: string): Implies

Every selected effect has a row whose column equals the effect's key. Source

queue ​

function queue(name: string, messages: readonly QueueMessage[]): QueueDrive

Drive the Worker's queue() handler with these messages from the named queue; an id defaults to msg-<n>. Source

queueAck ​

function queueAck(queueName: string): EffectSelector

Selects the acknowledgement that took effect for each message (explicit or implicit; not one ignored after a retry). Source

r2Bucket ​

function r2Bucket(binding: string, objects: Readonly<Record<string, R2Seed>> = {}): R2Setup

An R2 bucket the scenario uses: emptied before each run, then seeded with these objects by key. Source

r2Op ​

function r2Op(binding: string, op: "put" | "delete" | "get" | "head" | "list" = "put"): EffectSelector

Selects an R2 bucket's operations that completed, a put by default; a put whose onlyIf failed stored nothing and is not selected, as a D1 write that changed no row is not. Source

r2Rows ​

function r2Rows(binding: string, where?: readonly RowCondition[]): StateQuery

A bucket's objects at the end of the run as rows { key, size, etag, customMetadata, httpMetadata, text? }. Source

references ​

function references(name: string, query: StateQuery, path: string, inQuery: StateQuery, column: string): References

Every row the query returns is named by some row of in (its column equals the row's value at path), as with a foreign key. Source

refines ​

function refines(name: string, decision: string, effect: EffectSelector, options: Pick<Refines, "follows" | "state"> = {}): Refines

The shell follows the core function decision (see the refines invariant): every selected effect carries out the latest decision of its invocation, agrees with it on follows, and, with state, was not made stale by another invocation's write between the read it rests on and the effect. Source

rpc ​

function rpc(calls: readonly RpcCallInput[], options: RpcCallerOptions = {}): RpcDrive

Drive a WorkerEntrypoint of the Worker with these method calls; a call's id defaults to call-<n>. Source

rpcResponse ​

function rpcResponse(method: string, options: { readonly ok?: boolean; readonly entrypoint?: string } = {}): EffectSelector

Selects the answers an RPC method gave (ok narrows to values returned or to errors thrown). Source

runDifferential ​

function runDifferential(spec: ScenarioSpec, options: CloudflarePlatformOptions): Promise<DifferentialResult>

Run both sides and compare. Source

service ​

function service(binding: string, options: { readonly methods?: { readonly [method: string]: ScriptedReply }; readonly fetch?: readonly ServiceResponse[]; } = {}): ServiceSetup

Script the Worker behind a service binding: its RPC methods answer from methods and its fetch() from fetch, and the real binding is never called. Source

serviceCall ​

function serviceCall(binding: string, method?: string): EffectSelector

Selects the calls through a service binding that completed (scripted or a callee's), one method's or all. Source

snapshotD1 ​

function snapshotD1(real: D1Database): Promise<{ readonly [table: string]: readonly JsonValue[] }>

Every user table's rows, sorted canonically, read through the real binding (not an effect). Source

unique ​

function unique(name: string, query: StateQuery, path: string): Unique

No two rows the query selects share the value at path (a column, or a dot path into the row). Source

websocket ​

function websocket(connections: readonly WebSocketConnectionInput[]): WebSocketDrive

Drive the Worker over these WebSocket connections: each opened through its fetch() and handed to a Durable Object, its messages delivered in order to the object's webSocketMessage handler. Source

webSocketReceived ​

function webSocketReceived(connection: string): EffectSelector

Selects the frames the Worker sent on a connection (WebSocket:<connection>, op message), each recorded at the end of the run, in arrival order, with its data (JSON where it parses, text otherwise). Source

workflow ​

function workflow(binding: string, className: string, options: { readonly name?: string } = {}): WorkflowSetup

A Workflow binding and the class its instances run, an export of the Worker module; name is the Workflow's name in the wrangler config, which instances read as event.workflowName. Source

workflowRows ​

function workflowRows(binding: string, where?: readonly RowCondition[]): StateQuery

A Workflow's instances at the end of the run as rows { id, status, params, output?, error? }. Source

workflowStep ​

function workflowStep(binding: string, step?: string): EffectSelector

Selects a Workflow's step attempts, optionally of one step; a failed attempt's result carries its error. Source

Types ​

CalleeModule ​

interface CalleeModule

The callee's module as the test gives it: the Worker's name from its wrangler config, which qualifies its bindings, its exports, and what the caller's service binding carries in its own config: the entrypoint the binding reaches (the scenario's callee() may name one too, and wins) and the props the callee reads from ctx.props. Source

CalleeSetup ​

interface CalleeSetup

The Worker behind a service binding, run for real: its module and wrangler config, relative to the scenario, in place of a script. Source

CheckTransport ​

interface CheckTransport

What the generated test stores in its task meta. Source

CloudflarePlatformOptions ​

interface CloudflarePlatformOptions

What createCloudflarePlatform needs: the env and the Worker's default export, the schema per D1 binding, and for the bindings that need them the test helpers, the module's exports, the callees and the aliases. Source

CloudflareRegressionOptions ​

interface CloudflareRegressionOptions

What cloudflareRegressionTest needs to write the test: import paths of the scenario, the Worker and its schema files, relative to the emitted file, and what the platform was given when the check ran. Source

CloudflareScenarioInput ​

interface CloudflareScenarioInput

The input to defineScenario: the Worker, the drive, the setup steps, the externals it fetches, the invariants, the bounds (merged with the defaults) and the core modules whose specs run. Source

CronDrive ​

interface CronDrive

Drive the Worker's scheduled() handler with the ticks of a Cron Trigger: the expression's first ticks matches from the virtual epoch on, in UTC, each an event delivered at its virtual time. Source

CronOptions ​

interface CronOptions

How many ticks of the expression to drive, and how many times a tick whose handler failed is re-run. Source

CronTickSpec ​

type CronTickSpec

One tick of a Cron Trigger: its id and the virtual time it fires, which the handler sees as scheduledTime. Source

D1Setup ​

interface D1Setup

Apply a SQL file to a D1 binding before each run. Source

DifferentialResult ​

interface DifferentialResult

What runDifferential found: each side's attempts and end state, and where they differ. Source

DurableObjectSetup ​

interface DurableObjectSetup

Clear a Durable Object namespace before each run and seed the named objects' storage with these entries; its storage is snapshotted after the run for state invariants (see durableObjectRows). Source

DurableObjectSqlSeed ​

type DurableObjectSqlSeed

A SQLite-backed object's starting storage: its CREATE TABLE statements, and rows per table (plain data, as setup steps are). Source

DurableObjectTestHelpers ​

interface DurableObjectTestHelpers

The Cloudflare Vitest plugin's test helpers, as exported by cloudflare:test (pass the module namespace). Source

HttpCallerOptions ​

interface HttpCallerOptions

How the HTTP drive's caller resends a request it got no acceptable answer for: up to retries times (default 3), on a status retryOn rejects (default any non-2xx), after delaysMs of virtual time, and not waiting past deadlineMs. Source

HttpDrive ​

interface HttpDrive

Drive the Worker's fetch() handler with these requests. Source

HttpRequestInput ​

interface HttpRequestInput

One inbound request; id defaults to its position, method to POST with a body and GET without. Source

HttpRequestSpec ​

type HttpRequestSpec

A type alias, not an interface, so it is assignable to the JSON shape of PlatformData. Source

QueueDrive ​

interface QueueDrive

Drive the Worker's queue() handler with these messages. Source

QueueMessage ​

interface QueueMessage

One queue message to deliver; id defaults to its position. Source

R2Setup ​

interface R2Setup

An R2 bucket the scenario uses: emptied, then seeded with these objects, before each run. Source

RpcCallerOptions ​

interface RpcCallerOptions

The RPC drive's entrypoint (a named export; default the default export) and how its caller resends a call that threw or got no answer: retries (default 0), delaysMs and deadlineMs, as for http. Source

RpcCallInput ​

interface RpcCallInput

One RPC call; id defaults to its position, args to none. Source

RpcCallSpec ​

type RpcCallSpec

A type alias, not an interface, so it is assignable to the JSON shape of PlatformData. Source

RpcDrive ​

interface RpcDrive

Drive a WorkerEntrypoint of the Worker with these method calls, one invocation per attempt, the entrypoint constructed anew for each. Source

ScriptedReply ​

type ScriptedReply

A scripted method's reply: a value returned to the caller, or an error ("<Name>: <message>") thrown to it. Source

ServiceResponse ​

type ServiceResponse

A reply to fetch() through a service binding; a type alias of core's ScriptedResponse, for the JSON shape. Source

ServiceSetup ​

interface ServiceSetup

Script the Worker another Worker reaches through a service binding: its RPC methods answer from methods (every method returns null when omitted; a method missing from a present methods makes the run UNSUPPORTED) and its fetch() from fetch, matched by method and path as an external's responses are (200 with an empty body when omitted). Source

SpecEntry ​

interface SpecEntry

A generated spec entry: the module's specs, read on the Node side, and a loader of its spec file. Source

SqlRow ​

type SqlRow

One row to insert, or one row snapshotted: column name to value (booleans and objects as SQLite stores them). Source

WebSocketConnectionInput ​

interface WebSocketConnectionInput

One connection to open: the path of its upgrade request, its headers and the messages to send on it. Source

WebSocketDrive ​

interface WebSocketDrive

Drive the Worker over WebSocket connections: each connection is opened with an upgrade request to its path (one event) and its messages are sent in order (one event each, after its connection opened and its previous message was handled); every connection closes at the end of the run. Source

WebSocketMessageInput ​

interface WebSocketMessageInput

One message to send on a connection: its data (a JSON value is sent as its text) and an optional id. Source

WorkerdCheckInput ​

interface WorkerdCheckInput

What the generated check test passes to checkInWorkerd: the scenario, the bindings and test helpers, the modules and SQL files beside the scenario, the callees, and the exploration options. Source

WorkerEntrypointClass ​

type WorkerEntrypointClass

A WorkerEntrypoint subclass: the Worker's default export when it exposes RPC methods. Source

WorkerHandler ​

interface WorkerHandler

The Worker's default export, as far as the platform drives it. Source

WorkflowSetup ​

interface WorkflowSetup

A Workflow binding, and the class (an export of the Worker module) its instances run. Source