src/cloudflare/

OVERVIEW

TypeScript implementations of Cloudflare product APIs (AI, D1, R2, Vectorize, etc.).

• The internal/* directory contains internal implementation details not directly exposed to user code.
• The top-level .ts files are the public API entry points exposed to user code.

It is common, but not required, for top-level .ts files to re-export from internal/ via cloudflare-internal: specifiers. This allows for a clean separation between public API surface and internal implementation details.

STRUCTURE

• <product>.ts — Public entry point; e.g ai.ts for AI maps to cloudflare:ai
• internal/*.ts — Implementation; imports runtime types from sibling .d.ts
• internal/*.d.ts — Type declarations for C++ runtime-provided modules (no implementation)
• internal/tracing-helpers.ts — Shared instrumentation (withSpan); imported as cloudflare-internal:tracing-helpers
• internal/test/<product>/ — Per-product test directory

TEST PATTERN

Each product test directory contains:

File	Purpose
<product>-api-test.js	JS test; named exports with test() methods + node:assert
<product>-api-test.wd-test	Cap'n Proto config wiring test worker to mock
<product>-mock.js	Mock service simulating upstream API
<product>-api-test.py	Python variant (optional)
python-<product>-api-test.wd-test	Python test config (optional)
<product>-api-instrumentation-test.js	Tracing/instrumentation tests (optional)

Mock wiring uses wrapped bindings: moduleName = "cloudflare-internal:<product>-api" with innerBindings pointing fetcher at the mock service. Shared instrumentation-test-helper.js lives in internal/test/.