DEV Community: puffball1567

bgfx Instancing Tutorial: Draw 625 Cubes with One Draw Call

puffball1567 — Tue, 20 Oct 2026 16:27:13 +0000

If you draw 625 copies of the same cube, does the CPU need to submit 625 separate drawing commands? It can instead supply a list of placements and request the whole group at once. Instancing draws a shared mesh repeatedly, using different data for each copy.

GPU Implementation with bgfx is a series about building GPU effects and processing examples with bgfx. We use the library to make small working programs, connecting code to what appears on screen. This second installment uses a colorful field of moving cubes to explore how drawing commands can be combined.

The first demo arranged 25 × 25 cubes and animated their height in a vertex shader. Here we keep the same geometry, wave, and colors while reducing the cube submissions from 625 calls to one. An unchanged picture can be produced through a different data path.

You do not need prior experience with instancing. We will recap the relationship between geometry and drawing, then work through the changes using C++ arrays and loops. We will modify the previous cube renderer: keep its window, vertex and index buffers, and camera setup, then replace placement handling and the drawing loop. This is an independent tutorial, and I am not part of the bgfx team. The demo code was written for this article. bgfx uses the BSD 2-Clause license; SDL3, which creates the window, uses the zlib license.

1. Sharing geometry did not combine the draw calls

The cube is a mesh: a shape described by vertices and triangles. Each of its six square faces is split into two triangles, giving twelve triangles per cube.

The demo's vertex buffer, vb, stores positions and face normals. Its index buffer, ib, stores the vertex numbers that form each triangle. Both buffers are created once and shared by all cubes.

In the individual drawing path, each placement still receives a separate submission:

Shared cube mesh
  ├─ set placement A → submit
  ├─ set placement B → submit
  └─ …625 submissions

bgfx::submit submits a draw using the configured geometry, shader program, and rendering state. It does not mean the GPU has completed the drawing when the call returns. Drawing API

Instancing keeps the shared geometry and changes how placements are supplied:

Shared mesh ─────────────────────────────┐
                                         ├─ one submit → 625 cubes
Placement records [A, B, C, …625 records] ─┘

Each placement record belongs to an instance, one copy of the shared shape. The GPU draws the mesh using each record. This does not divide the triangle count by 625.

2. What changes from the previous implementation

We will change how the CPU supplies placements and how the vertex shader receives them.

Location	Previous implementation	This implementation
C++ rendering loop	Set a model matrix and submit each cube	Fill a list of centers and submit the group
Vertex shader	Obtain placement from a model matrix	Read placement from instance input
Shader input definitions	Vertex positions and normals	Add one center per instance
Fragment shader	Compute color and shading	Keep the same computation

Put the C++ changes in main.cpp and the additional input definition in varying.def.sc. Create vs_instanced.sc for the new vertex shader and pair it with the existing fs_wave.sc. Keep vs_wave.sc for comparison.

The explanation focuses on changes to the previous renderer. The complete files at the end include window creation, rendering, building, and verification, so you can also try the program without having the previous project.

The target is Linux, SDL3/X11, the bgfx API 159 SDK, and the OpenGL backend. Use matching headers, libraries, and shaderc. Other backends need their corresponding shader binaries.

Use SDL3 for the window and input

When adapting the first installment, migrate its SDL initialization too. SDL3 owns the window and input; bgfx handles rendering. No custom library such as CBSS is needed.

Include <SDL3/SDL.h> and, in the file defining main, <SDL3/SDL_main.h>. SDL_Init returns true on success, so check failure with if (!SDL_Init(SDL_INIT_VIDEO)). Update the compiler and linker flags to use pkg-config --cflags --libs sdl3. SDL3 migration guide

After successfully creating window, obtain its X11 handles through properties:

const SDL_PropertiesID properties = SDL_GetWindowProperties(window);
void* display = SDL_GetPointerProperty(
    properties, SDL_PROP_WINDOW_X11_DISPLAY_POINTER, nullptr);
const Sint64 nativeWindow = SDL_GetNumberProperty(
    properties, SDL_PROP_WINDOW_X11_WINDOW_NUMBER, 0);
if (!display || nativeWindow == 0) {
    std::fprintf(stderr, "This demo requires SDL3 X11.\n");
    SDL_DestroyWindow(window);
    SDL_Quit();
    return 1;
}

// init is a bgfx::Init. Set these fields before bgfx::init(init).
init.swapChain.ndt = display;
init.swapChain.nwh = reinterpret_cast<void*>(uintptr_t(nativeWindow));

display identifies the X11 connection; nativeWindow identifies the native window. Do not pass the SDL window pointer itself as the native handle. This example selects X11/XWayland with SDL_SetHint(SDL_HINT_VIDEO_DRIVER, "x11") before initialization. Window properties API

Use SDL_EVENT_QUIT for exit events and SDL_EVENT_KEY_DOWN for key presses. Read the key from event.key.key; the R key constant is SDLK_R. The instance buffers and shaders below belong to bgfx rather than SDL.

3. Each cube only needs a center position

The previous version used a 4 × 4 model matrix for each cube. Since these cubes neither rotate nor scale, a center position is sufficient.

X represents the horizontal direction, Y represents height, and Z represents depth. Looking toward the origin from negative Z, positive X points right, positive Y points up, and positive Z points away from you. The demo camera looks from above at an angle, so screen-right does not necessarily match positive X.

We represent a placement with four floats:

// A center 1.12 units along positive X from the origin.
const float record[4] = {1.12f, 0.0f, 0.0f, 0.0f};

The first three components are X, Y, and Z; the fourth is unused. A transient instance record in bgfx needs a size that is a multiple of 16 bytes. In this SDK, four floats occupy 16 bytes. The distance from one record to the next is called its stride. Instance buffer API

First 16-byte record          Second 16-byte record
[ centerX, Y, Z, unused ]     [ centerX, Y, Z, unused ] …
           ↓                            ↓
        Cube 1                       Cube 2

Vertex data and instance data have different jobs. A vertex position identifies a corner within the cube; the instance center places that cube in the scene. All vertices belonging to the same instance use the same center.

4. Allocate space for this frame

Before the rendering loop, define the count and stride:

constexpr uint16_t instanceStride = 16;
constexpr uint32_t instanceCount = gridSize * gridSize; // 25 × 25 = 625

Each frame, check capacity before allocating the records. This excerpt comes from the demo's instancing path:

// The API returns an available record count, not a boolean.
const bool useInstancing = !individual &&
    bgfx::getAvailInstanceDataBuffer(instanceCount, instanceStride) == instanceCount;

if (useInstancing) {
    bgfx::InstanceDataBuffer instances;
    // The function fills the structure passed through its first argument.
    bgfx::allocInstanceDataBuffer(&instances, instanceCount, instanceStride);
    // Fill the records and configure the draw here.
}

individual is a boolean used to compare the rendering paths. Declare bool individual = false; before the rendering loop. Set it to true for individual draws, or false to use instancing when capacity permits.

instances is a description of the allocation, not an inline array containing 625 cubes. instances.data points to the writable bytes, instances.stride gives the record spacing, and instances.num gives the instance count. In C++, &instances passes the address of that structure.

This allocation is temporary and belongs to the current frame. Do not retain its pointer across the next bgfx::frame(); allocate again in the next frame. It does not require your own delete or bgfx::destroy. If there is insufficient capacity, use the previous individual drawing loop in the else branch instead of leaving cubes out. Allocation and lifetime contract

5. Write the placement records

This loop runs inside the preceding if, immediately after allocation:

for (int z = 0; z < gridSize; ++z) {
    for (int x = 0; x < gridSize; ++x) {
        // Subtract 12 from indices 0–24 to center the grid on the origin.
        const float record[4] = {(x-12)*1.12f, 0.0f, (z-12)*1.12f, 0.0f};
        const uint32_t index = uint32_t(z * gridSize + x);
        // Move index records into the buffer, then copy four floats as bytes.
        std::memcpy(instances.data + index * instances.stride, record, sizeof(record));
    }
}

x and z are grid indices, not distances. At x = 13, z = 12, the center becomes (1.12, 0, 0). The spacing of 1.12 leaves a gap of 0.20 between cubes whose side length is 0.92 when the grid is flat.

index flattens the two-dimensional grid into a list. The first row occupies records 0–24, the next 25–49, and so on. At z = 1, x = 2, the index is 27. Its record begins 27 × 16 = 432 bytes from the start.

Include <cstring> for std::memcpy. Copying transfers the local array's contents into bgfx's allocation. Creating another record on the next loop iteration does not remove the bytes already written.

The CPU still executes a nested loop. What changes is the repeated per-cube state setup and submission.

6. Receive instance positions in the shader

Add an instance input to varying.def.sc. This declaration follows the 05-instancing example supplied with the API 159 SDK used here:

vec4 i_data0 : TEXCOORD31;

i_data0 receives the four floats in a record. TEXCOORD31 identifies the input mapping; it does not cause a texture image to be read. Official sample input definitions

The web documentation also contains declarations starting at TEXCOORD7. SDK generations differ, so avoid mixing an input declaration from another generation with your shader compiler. This demo uses the declaration and shaderc from the same SDK.

Declare the input at the beginning of the vertex shader too:

$input a_position, a_normal, i_data0
$output v_normal, v_world, v_local
#include <bgfx_shader.sh>
uniform vec4 u_wave;

a_position and a_normal vary by vertex. i_data0 varies by instance. u_wave is a uniform shared by the draw: its .x component holds elapsed seconds, and .y holds the wave amplitude.

The shader's main() uses these values as follows:

void main()
{
    // Every vertex in this cube receives the same center.
    vec3 center = i_data0.xyz;
    float radius = length(center.xz);
    float height = u_wave.y * (
        sin(radius * 0.65 - u_wave.x * 1.8)
        + 0.35 * cos(center.x * 0.5 + center.z * 0.35 + u_wave.x));

    // Move the local vertex into the scene, then add the wave height.
    vec3 world = a_position + center;
    world.y += height;
    gl_Position = mul(u_viewProj, vec4(world, 1.0));

    // Translation changes neither the direction nor length of the normal.
    v_normal = a_normal;
    v_world = world;
    v_local = a_position;
}

center.xz selects the horizontal coordinates, and length finds their distance from the origin. The sine term produces a radial wave, with a smaller cosine wave added to it. Calculating height from the center gives every vertex in one cube the same vertical displacement, preserving its shape.

For example, a vertex at (0.46, 0.46, 0.46) and a center at (1.12, 0, 0) produce (1.58, 0.46, 0.46) before adding the wave. We then add height to Y and use u_viewProj to apply the camera and projection transformations. Predefined bgfx uniforms

This shader does not read a model matrix, so the instanced path does not call setTransform. To add rotation, supply suitable rotation data and implement that transformation too. Instancing does not automatically construct a matrix.

7. Bind the list and submit once

During initialization, the demo's loadProgram helper combines the vertex and fragment shaders:

// assets identifies the directory containing the executable and shader binaries.
auto instancedProgram = loadProgram(assets, "vs_instanced.bin", "fs_wave.bin");
auto uWave = bgfx::createUniform("u_wave", bgfx::UniformType::Vec4);

loadProgram is a demo helper, not a bgfx API. It reads the binaries and calls createShader and createProgram. The reference and instanced paths use different vertex shaders but share the fragment shader.

Each frame, after filling the allocation, configure the draw inside the same if block. wave is the frame's float array containing {time, amplitude, 0, 0}.

bgfx::setVertexBuffer(0, vb);                  // Shared geometry
bgfx::setIndexBuffer(ib);                     // Triangle connectivity
bgfx::setInstanceDataBuffer(&instances);      // 625 placements
bgfx::setUniform(uWave, wave);                // Shared time and amplitude
bgfx::setState(BGFX_STATE_WRITE_RGB | BGFX_STATE_WRITE_A |
               BGFX_STATE_WRITE_Z | BGFX_STATE_DEPTH_TEST_LESS);
bgfx::submit(0, instancedProgram);            // One submission for the cubes

The bound instance count determines how many copies are drawn. The 0 in setVertexBuffer identifies a vertex stream; the 0 in submit identifies a view.

Depth handling remains the same. WRITE_Z records depth, and DEPTH_TEST_LESS selects nearer surfaces. A separate draw adds the title overlay before bgfx::frame(). One draw refers to the cubes; the complete image uses two submissions including the overlay.

8. Assemble the changes and verify the result

Place the pieces in the per-frame loop in this order:

Build the wave array from time and amplitude
  ↓
Check transient capacity for 625 records
  ├─ Enough capacity and individual is false
  │    Allocate → write placements → bind buffers → submit once
  └─ Otherwise
       Use the previous nested loop: set a model matrix → submit 625 times
  ↓
Draw the title and any other elements
  ↓
bgfx::frame()

Compile the new vertex shader before loading it. Set BGFX_SDK to the directory containing bgfx, bx, and bimg, then run this from the project root. Adjust the compiler path if your SDK stores shadercRelease elsewhere.

# Compile the new vertex shader for OpenGL.
mkdir -p build
"$BGFX_SDK/bgfx/.build/linux64_gcc/bin/shadercRelease" \
  -f shaders/vs_instanced.sc -o build/vs_instanced.bin \
  --type vertex --platform linux -p 330 \
  --varyingdef shaders/varying.def.sc -i "$BGFX_SDK/bgfx/src"

Rebuild the C++ program using the same dependencies as before. Match the filename and location of vs_instanced.bin to what loadProgram reads. Saving shader source alone does not update the binary loaded by the program.

First check the individual path with individual = true, then change it to false and rebuild. The count, placement, movement, and colors should remain the same. After rendering several frames, inspect the submission count:

// These statistics describe a rendered frame; do not compare immediately after initialization.
const bgfx::Stats* stats = bgfx::getStats();
std::printf("Submitted draws: %u\n", stats->numDraw);

The statistics include more than cubes. The verification program draws one title overlay and omits the empty submission made by touch, giving 626 for individual rendering and 2 for instancing. Account for any additional UI or other drawing in your application.

For a strict visual comparison, fix time and amplitude. With times 0 and 2 seconds and amplitudes 0 and 1.35, all four pairs were pixel-identical in this OpenGL run. Changing time had no effect at zero amplitude, while the enabled wave moved. Capacity exhaustion did not occur in these checks.

Fewer submissions do not imply a fixed speedup

The cube submissions drop from 625 to one. The program still draws twelve triangles for each of 625 cubes, calculates wave heights, and shades the covered pixels. A 625-fold reduction in submissions is not a 625-fold reduction in frame time.

The instance records occupy 625 × 16 = 10,000 bytes. That is the placement data we write, not a measurement of all transferred data. The CPU fills it every frame. Since placement is constant in this demo, a persistent buffer is another possible implementation. Here, transient allocation makes the write and lifetime sequence explicit.

Combining draws also requires compatible inputs and state. These cubes share their mesh, shader, and rendering state; only placement differs. Different geometry, materials, or ordering requirements for transparency may require separate groups. Start by identifying what is shared and what varies by instance.

A future installment can change the image itself: render to a target, extract bright areas, and blur them into a glow. That shifts the focus from passing a list of shapes to passing images between rendering stages.

Complete source by file

Below is the complete SDL3 implementation. Save each code block under its filename. These are full files used by the demo, not abbreviated excerpts. The SDK and SDL3 itself are separate dependencies.

Create a working directory named demo-instanced-cubes and a shaders subdirectory. Save files whose names begin with shaders/ there, and the remaining files in the working directory. The build creates build/ and generates the title image.

You need Linux with X11/XWayland, a C++20-capable g++, pkg-config, SDL3 development headers and libraries, X11 development libraries, Python 3 with Pillow, and DejaVu Sans fonts. Also provide the bgfx API 159 SDK with matching bx, bimg, and shaderc. See the bgfx build guide and SDL3 installation guide. This implementation was run with SDL 3.3.0.

The directory identified by BGFX_SDK contains sibling bgfx/, bx/, and bimg/ directories. By default the script reads shadercRelease, libbgfxRelease.a, libbimgRelease.a, and libbxRelease.a from bgfx/.build/linux64_gcc/bin/. Override BGFX_LIB_DIR and SHADERC if your outputs are elsewhere.

The complete program accepts --individual to select the reference path without editing the source. Its default is instancing, with individual rendering as a fallback when transient capacity is insufficient.

`demo_support.h`

#pragma once
#include <bgfx/bgfx.h>
#include <bx/math.h>
#include <SDL3/SDL.h>
#include <algorithm>
#include <array>
#include <cstdarg>
#include <cstdio>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <stdexcept>
#include <string>
#include <vector>

constexpr uint32_t width = 1280, height = 800;
constexpr int gridSize = 25;

// bgfx delivers screenshots from its renderer; capture only this application's pixels.
struct Capture final : bgfx::CallbackI {
    void fatal(const char* file, uint16_t line, bgfx::Fatal::Enum, const char* msg) override {
        std::fprintf(stderr, "bgfx fatal %s:%u: %s\n", file, line, msg);
        std::abort();
    }
    void traceVargs(const char*, uint16_t, const char* format, va_list args) override {
        std::vfprintf(stderr, format, args);
    }
    void profilerBegin(const char*, uint32_t, const char*, uint16_t) override {}
    void profilerBeginLiteral(const char*, uint32_t, const char*, uint16_t) override {}
    void profilerEnd() override {}
    uint32_t cacheReadSize(uint64_t) override { return 0; }
    bool cacheRead(uint64_t, void*, uint32_t) override { return false; }
    void cacheWrite(uint64_t, const void*, uint32_t) override {}
    void screenShot(const char* path, uint32_t w, uint32_t h, uint32_t pitch,
                    bgfx::TextureFormat::Enum format, const void* data, uint32_t, bool flip) override {
        if (format != bgfx::TextureFormat::BGRA8 && format != bgfx::TextureFormat::RGBA8)
            fatal(__FILE__, __LINE__, bgfx::Fatal::DebugCheck, "Unsupported screenshot format");
        std::ofstream file(path, std::ios::binary);
        file << "P6\n" << w << ' ' << h << "\n255\n";
        const auto* pixels = static_cast<const uint8_t*>(data);
        std::vector<char> rgb(size_t(w)*h*3);
        for (uint32_t y = 0; y < h; ++y) {
            const auto* row = pixels + (flip ? h - 1 - y : y) * pitch;
            for (uint32_t x = 0; x < w; ++x) {
                const auto* p = row + 4*x;
                auto offset=(size_t(y)*w+x)*3;
                rgb[offset] = char(p[format == bgfx::TextureFormat::BGRA8 ? 2 : 0]);
                rgb[offset+1] = char(p[1]);
                rgb[offset+2] = char(p[format == bgfx::TextureFormat::BGRA8 ? 0 : 2]);
            }
        }
        file.write(rgb.data(), std::streamsize(rgb.size()));
        if (!file) fatal(__FILE__, __LINE__, bgfx::Fatal::DebugCheck, "Screenshot write failed");
    }
    void captureBegin(uint32_t, uint32_t, uint32_t, bgfx::TextureFormat::Enum, bool) override {}
    void captureEnd() override {}
    void captureFrame(const void*, uint32_t) override {}
};

std::vector<char> readFile(const std::filesystem::path& path) {
    std::ifstream input(path, std::ios::binary | std::ios::ate);
    if (!input) throw std::runtime_error("Cannot open " + path.string());
    const auto length = input.tellg();
    if (length <= 0) throw std::runtime_error("Empty file " + path.string());
    std::vector<char> bytes(static_cast<size_t>(length));
    input.seekg(0);
    input.read(bytes.data(), length);
    if (!input) throw std::runtime_error("Cannot read " + path.string());
    return bytes;
}

bgfx::ProgramHandle loadProgram(const std::filesystem::path& dir, const char* vs, const char* fs) {
    auto vb = readFile(dir / vs), fb = readFile(dir / fs);
    auto v = bgfx::createShader(bgfx::copy(vb.data(), uint32_t(vb.size())));
    auto f = bgfx::createShader(bgfx::copy(fb.data(), uint32_t(fb.size())));
    if (!bgfx::isValid(v) || !bgfx::isValid(f)) {
        if (bgfx::isValid(v)) bgfx::destroy(v);
        if (bgfx::isValid(f)) bgfx::destroy(f);
        throw std::runtime_error("Shader creation failed");
    }
    auto program = bgfx::createProgram(v, f, true); // Program owns these shader references.
    if (!bgfx::isValid(program)) throw std::runtime_error("Program creation failed");
    return program;
}

struct Vertex { float x, y, z, nx, ny, nz; };
struct OverlayVertex { float x, y, z, u, v; };

`main.cpp`

#include "demo_support.h"
#include <cstring>
#include <SDL3/SDL_main.h>

int main(int argc, char** argv) {
    int frameLimit = 0;
    float startTime = 0.0f, amplitude = 1.35f;
    bool fixedTime = false, paused = false, individual = false;
    std::string screenshot, recordDir;
    // Explicit deterministic controls let the validation script compare real rendered frames.
    try {
        for (int i = 1; i < argc; ++i) {
            std::string arg = argv[i];
            auto value = [&]() { if (++i >= argc) throw std::runtime_error("Missing argument"); return argv[i]; };
            if (arg == "--individual") individual = true;
            else if (arg == "--frames") frameLimit = std::stoi(value());
            else if (arg == "--time") { startTime = std::stof(value()); fixedTime = true; }
            else if (arg == "--amplitude") amplitude = std::stof(value());
            else if (arg == "--screenshot") screenshot = value();
            else if (arg == "--record") recordDir = value();
            else throw std::runtime_error("Unknown argument: " + arg);
        }
        if ((!screenshot.empty() || !recordDir.empty()) && frameLimit < 4)
            throw std::runtime_error("Capture requires --frames >= 4");
        if (!recordDir.empty()) std::filesystem::create_directories(recordDir);
    } catch (const std::exception& e) { std::fprintf(stderr, "%s\n", e.what()); return 1; }

    // This demonstrator deliberately selects SDL's X11 path and bgfx's OpenGL backend.
    SDL_SetHint(SDL_HINT_VIDEO_DRIVER, "x11");
    if (!SDL_Init(SDL_INIT_VIDEO)) { std::fprintf(stderr, "%s\n", SDL_GetError()); return 1; }
    SDL_Window* window = SDL_CreateWindow("GPU Sketchbook | Instanced cubes", width, height,
        recordDir.empty() && screenshot.empty() ? 0 : SDL_WINDOW_HIDDEN);
    if (!window) { std::fprintf(stderr, "%s\n", SDL_GetError()); SDL_Quit(); return 1; }
    // SDL3 exposes native handles through window properties instead of SDL_SysWMinfo.
    const SDL_PropertiesID properties = SDL_GetWindowProperties(window);
    void* display = SDL_GetPointerProperty(properties, SDL_PROP_WINDOW_X11_DISPLAY_POINTER, nullptr);
    const Sint64 nativeWindow = SDL_GetNumberProperty(properties, SDL_PROP_WINDOW_X11_WINDOW_NUMBER, 0);
    if (!display || nativeWindow == 0) {
        std::fprintf(stderr, "This demo requires SDL3 X11 (XWayland is fine).\n");
        SDL_DestroyWindow(window); SDL_Quit(); return 1;
    }
    Capture capture;
    bgfx::Init init;
    init.type = bgfx::RendererType::OpenGL;
    init.fallback = false; // A backend change would require matching shader binaries.
    init.swapChain.nwh = reinterpret_cast<void*>(uintptr_t(nativeWindow));
    init.swapChain.ndt = display;
    init.swapChain.width = width;
    init.swapChain.height = height;
    init.reset = BGFX_RESET_VSYNC;
    init.callback = &capture;
    if (!bgfx::init(init)) { SDL_DestroyWindow(window); SDL_Quit(); return 1; }
    int result = 0;
    try {
        const auto assets = std::filesystem::canonical(argv[0]).parent_path();
        std::vector<Vertex> vertices;
        std::vector<uint16_t> indices;
        // Four distinct vertices per face preserve a flat face normal at each corner.
        const float normals[6][3] = {{1,0,0},{-1,0,0},{0,1,0},{0,-1,0},{0,0,1},{0,0,-1}};
        for (int face = 0; face < 6; ++face) {
            const int axis = face / 2, a = (axis + 1) % 3, b = (axis + 2) % 3;
            const uint16_t base = uint16_t(vertices.size());
            for (int corner = 0; corner < 4; ++corner) {
                float p[3]{};
                p[axis] = (face % 2 == 0 ? 0.46f : -0.46f);
                p[a] = (corner == 1 || corner == 2) ? 0.46f : -0.46f;
                p[b] = corner >= 2 ? 0.46f : -0.46f;
                vertices.push_back({p[0],p[1],p[2],normals[face][0],normals[face][1],normals[face][2]});
            }
            for (uint16_t offset : {0,1,2,0,2,3}) indices.push_back(base + offset);
        }
        bgfx::VertexLayout layout;
        layout.begin().add(bgfx::Attrib::Position, 3, bgfx::AttribType::Float)
                      .add(bgfx::Attrib::Normal, 3, bgfx::AttribType::Float).end();
        auto vb = bgfx::createVertexBuffer(bgfx::copy(vertices.data(), uint32_t(vertices.size()*sizeof(Vertex))), layout);
        auto ib = bgfx::createIndexBuffer(bgfx::copy(indices.data(), uint32_t(indices.size()*sizeof(uint16_t))));
        auto program = loadProgram(assets, "vs_wave.bin", "fs_wave.bin");
        auto instancedProgram = loadProgram(assets, "vs_instanced.bin", "fs_wave.bin");
        // Each record is one center position plus an unused fourth float.
        constexpr uint16_t instanceStride = 16;
        constexpr uint32_t instanceCount = gridSize * gridSize;
        uint32_t instancedFrames = 0, individualFrames = 0;
        auto uWave = bgfx::createUniform("u_wave", bgfx::UniformType::Vec4);

        // A separate screen-space pass adds only typography, not the 3D effect.
        const OverlayVertex quad[] = {{-1,1,0,0,0},{1,1,0,1,0},{1,-1,0,1,1},{-1,-1,0,0,1}};
        const uint16_t quadIndices[] = {0,1,2,0,2,3};
        bgfx::VertexLayout overlayLayout;
        overlayLayout.begin().add(bgfx::Attrib::Position, 3, bgfx::AttribType::Float)
                             .add(bgfx::Attrib::TexCoord0, 2, bgfx::AttribType::Float).end();
        auto overlayVb = bgfx::createVertexBuffer(bgfx::copy(quad, sizeof(quad)), overlayLayout);
        auto overlayIb = bgfx::createIndexBuffer(bgfx::copy(quadIndices, sizeof(quadIndices)));
        auto overlayProgram = loadProgram(assets, "vs_overlay.bin", "fs_overlay.bin");
        auto overlayBytes = readFile(assets / "overlay.rgba");
        if (overlayBytes.size() != width * height * 4) throw std::runtime_error("Wrong overlay size");
        auto overlayTexture = bgfx::createTexture2D(width, height, false, 1, bgfx::TextureFormat::RGBA8,
            BGFX_SAMPLER_U_CLAMP | BGFX_SAMPLER_V_CLAMP, bgfx::copy(overlayBytes.data(), uint32_t(overlayBytes.size())));
        auto overlaySampler = bgfx::createUniform("s_overlay", bgfx::UniformType::Sampler);
        if (!bgfx::isValid(vb) || !bgfx::isValid(ib) || !bgfx::isValid(uWave) ||
            !bgfx::isValid(overlayVb) || !bgfx::isValid(overlayIb) ||
            !bgfx::isValid(overlayTexture) || !bgfx::isValid(overlaySampler))
            throw std::runtime_error("Resource creation failed");

        bgfx::setViewClear(0, BGFX_CLEAR_COLOR | BGFX_CLEAR_DEPTH, 0x0b1020ff, 1.0f, 0);
        bgfx::setViewRect(0, 0, 125, width, 605);
        bgfx::setViewRect(1, 0, 0, width, height);
        float view[16], projection[16];
        bx::mtxLookAt(view, {27.0f, 25.0f, -32.0f}, {0.0f, 0.0f, 0.0f});
        bx::mtxOrtho(projection, -25.0f, 25.0f, -11.82f, 11.82f, 0.1f, 120.0f,
                     0.0f, bgfx::getCaps()->homogeneousDepth);
        bgfx::setViewTransform(0, view, projection);
        bgfx::setViewClear(1, BGFX_CLEAR_NONE);
        std::printf("Renderer: %s; vendor=0x%04x device=0x%04x; cubes=%d\n",
            bgfx::getRendererName(bgfx::getRendererType()), bgfx::getCaps()->vendorId,
            bgfx::getCaps()->deviceId, gridSize*gridSize);
        uint64_t previous = SDL_GetPerformanceCounter();
        float time = startTime;
        bool running = true;
        int frame = 0;
        while (running && (frameLimit == 0 || frame < frameLimit)) {
            SDL_Event event;
            while (SDL_PollEvent(&event)) {
                if (event.type == SDL_EVENT_QUIT) running = false;
                if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat) {
                    switch (event.key.key) {
                    case SDLK_ESCAPE: running = false; break;
                    case SDLK_SPACE: paused = !paused; break;
                    case SDLK_UP: amplitude = std::min(3.0f, amplitude + 0.15f); break;
                    case SDLK_DOWN: amplitude = std::max(0.0f, amplitude - 0.15f); break;
                    case SDLK_R: time = 0.0f; amplitude = 1.35f; paused = false; break;
                    default: break;
                    }
                }
            }
            const uint64_t now = SDL_GetPerformanceCounter();
            if (!paused && !fixedTime) time += float(double(now-previous)/double(SDL_GetPerformanceFrequency()));
            previous = now;
            if (!recordDir.empty()) time = startTime + float(frame)/30.0f;
            const float wave[4] = {time, amplitude, 0.0f, 0.0f};
            // Check capacity before allocation. Never silently omit cubes.
            const bool useInstancing = !individual &&
                bgfx::getAvailInstanceDataBuffer(instanceCount, instanceStride) == instanceCount;
            if (useInstancing) {
                bgfx::InstanceDataBuffer instances;
                bgfx::allocInstanceDataBuffer(&instances, instanceCount, instanceStride);
                for (int z = 0; z < gridSize; ++z) {
                    for (int x = 0; x < gridSize; ++x) {
                        const float record[4] = {(x-12)*1.12f, 0.0f, (z-12)*1.12f, 0.0f};
                        const uint32_t index = uint32_t(z * gridSize + x);
                        // Copy bytes without assuming float alignment of the returned pointer.
                        std::memcpy(instances.data + index * instances.stride, record, sizeof(record));
                    }
                }
                bgfx::setVertexBuffer(0, vb);
                bgfx::setIndexBuffer(ib);
                bgfx::setInstanceDataBuffer(&instances);
                bgfx::setUniform(uWave, wave);
                bgfx::setState(BGFX_STATE_WRITE_RGB | BGFX_STATE_WRITE_A |
                               BGFX_STATE_WRITE_Z | BGFX_STATE_DEPTH_TEST_LESS);
                bgfx::submit(0, instancedProgram);
                ++instancedFrames;
            } else {
                // Reference path also handles insufficient transient capacity.
                for (int z = 0; z < gridSize; ++z) {
                    for (int x = 0; x < gridSize; ++x) {
                        float model[16];
                        // CPU places cube centers on a flat grid. GPU calculates their height.
                        bx::mtxTranslate(model, (x-12)*1.12f, 0.0f, (z-12)*1.12f);
                        bgfx::setTransform(model);
                        bgfx::setVertexBuffer(0, vb);
                        bgfx::setIndexBuffer(ib);
                        bgfx::setUniform(uWave, wave);
                        // Culling is deliberately disabled; opposite cube faces have independent vertices.
                        bgfx::setState(BGFX_STATE_WRITE_RGB | BGFX_STATE_WRITE_A |
                                       BGFX_STATE_WRITE_Z | BGFX_STATE_DEPTH_TEST_LESS);
                        bgfx::submit(0, program);
                    }
                }
                ++individualFrames;
            }
            bgfx::setVertexBuffer(0, overlayVb);
            bgfx::setIndexBuffer(overlayIb);
            bgfx::setTexture(0, overlaySampler, overlayTexture);
            bgfx::setState(BGFX_STATE_WRITE_RGB | BGFX_STATE_WRITE_A | BGFX_STATE_BLEND_ALPHA);
            bgfx::submit(1, overlayProgram);
            if (!recordDir.empty()) {
                char name[64]; std::snprintf(name, sizeof(name), "/frame-%04d.ppm", frame);
                bgfx::requestScreenShot(BGFX_INVALID_HANDLE, (recordDir + name).c_str());
            } else if (!screenshot.empty() && frame == frameLimit-2) {
                bgfx::requestScreenShot(BGFX_INVALID_HANDLE, screenshot.c_str());
            }
            bgfx::frame();
            ++frame;
        }
        const auto* stats = bgfx::getStats();
        std::printf("Completed %d frames; last frame draws=%u; amplitude=%.2f; time=%.3f\n",
                    frame, stats->numDraw, amplitude, time);
        std::printf("Instanced frames=%u; individual frames=%u\n",
                    instancedFrames, individualFrames);
        if (bgfx::isValid(instancedProgram)) bgfx::destroy(instancedProgram);
        bgfx::destroy(overlaySampler); bgfx::destroy(overlayTexture);
        bgfx::destroy(overlayProgram); bgfx::destroy(overlayVb); bgfx::destroy(overlayIb);
        bgfx::destroy(uWave); bgfx::destroy(program); bgfx::destroy(vb); bgfx::destroy(ib);
    } catch (const std::exception& e) { std::fprintf(stderr, "%s\n", e.what()); result = 1; }
    bgfx::shutdown(); // Finish renderer work before destroying the native window or callback.
    SDL_DestroyWindow(window);
    SDL_Quit();
    return result;
}

`shaders/varying.def.sc`

vec3 a_position : POSITION;
vec3 a_normal : NORMAL;
vec2 a_texcoord0 : TEXCOORD0;
vec3 v_normal : TEXCOORD1;
vec3 v_world : TEXCOORD2;
vec3 v_local : TEXCOORD3;
vec2 v_uv : TEXCOORD0;
vec4 i_data0 : TEXCOORD31;

`shaders/vs_instanced.sc`

$input a_position, a_normal, i_data0
$output v_normal, v_world, v_local
#include <bgfx_shader.sh>

// x: time in seconds, y: amplitude, z/w: unused.
uniform vec4 u_wave;

void main()
{
    // One record per cube: all its vertices receive the same center.
    vec3 center = i_data0.xyz;
    float radius = length(center.xz);
    float height = u_wave.y * (
        sin(radius * 0.65 - u_wave.x * 1.8)
        + 0.35 * cos(center.x * 0.5 + center.z * 0.35 + u_wave.x));
    vec3 world = a_position + center;
    world.y += height;
    gl_Position = mul(u_viewProj, vec4(world, 1.0));
    // Placement only translates; normals need no rotation or rescaling.
    v_normal = a_normal;
    v_world = world;
    v_local = a_position;
}

`shaders/vs_wave.sc`

$input a_position, a_normal
$output v_normal, v_world, v_local
#include <bgfx_shader.sh>

// x: time in seconds, y: amplitude, z/w: unused.
uniform vec4 u_wave;

void main()
{
    // Transform the cube's center separately: every corner gets the same height.
    vec3 center = mul(u_model[0], vec4(0.0, 0.0, 0.0, 1.0)).xyz;
    float radius = length(center.xz);
    float height = u_wave.y * (
        sin(radius * 0.65 - u_wave.x * 1.8)
        + 0.35 * cos(center.x * 0.5 + center.z * 0.35 + u_wave.x));
    vec3 world = mul(u_model[0], vec4(a_position, 1.0)).xyz;
    world.y += height;
    gl_Position = mul(u_viewProj, vec4(world, 1.0));
    // Model matrices only translate; normals need no rotation or rescaling here.
    v_normal = a_normal;
    v_world = world;
    v_local = a_position;
}

`shaders/fs_wave.sc`

$input v_normal, v_world, v_local
#include <bgfx_shader.sh>

void main()
{
    // A spatial palette: raised cubes also move through the color gradient.
    float phase = v_world.x * 0.022 + v_world.z * 0.018 + v_world.y * 0.055;
    vec3 color = 0.55 + 0.45 * cos(6.2831853 *
        (vec3(phase, phase, phase) + vec3(0.02, 0.35, 0.65)));
    float light = 0.32 + 0.68 * max(dot(normalize(v_normal),
        normalize(vec3(-0.45, 0.85, -0.55))), 0.0);
    // The second-largest local coordinate approaches 0.46 near a face edge.
    vec3 p = abs(v_local);
    float edgeCoordinate = max(min(p.x, p.y), max(min(p.y, p.z), min(p.z, p.x)));
    float edge = smoothstep(0.425, 0.455, edgeCoordinate);
    color = color * light + edge * vec3(0.12, 0.18, 0.22);
    gl_FragColor = vec4(color, 1.0);
}

`shaders/vs_overlay.sc`

$input a_position, a_texcoord0
$output v_uv
#include <bgfx_shader.sh>
void main()
{
    gl_Position = vec4(a_position, 1.0);
    v_uv = a_texcoord0;
}

`shaders/fs_overlay.sc`

$input v_uv
#include <bgfx_shader.sh>
SAMPLER2D(s_overlay, 0);
void main()
{
    gl_FragColor = texture2D(s_overlay, v_uv);
}

`make_overlay.py`

"""Create the demo's transparent title card; no screenshot manipulation."""
from pathlib import Path
from PIL import Image, ImageDraw, ImageFont

root = Path(__file__).resolve().parent
out = root / "build"
out.mkdir(exist_ok=True)
im = Image.new("RGBA", (1280, 800))
d = ImageDraw.Draw(im)
d.rectangle((0, 0, 1279, 124), fill="#0b1020")
d.rectangle((0, 730, 1279, 799), fill="#0b1020")
fonts = Path("/usr/share/fonts/truetype/dejavu")
def font(size, bold=False):
    return ImageFont.truetype(str(fonts / ("DejaVuSans-Bold.ttf" if bold else "DejaVuSans.ttf")), size)

d.rounded_rectangle((46, 38, 53, 61), 3, fill="#6ee7dc")
d.text((65, 38), "GPU SKETCHBOOK  /  02", font=font(16, True), fill="#94b4c3")
d.text((44, 72), "625 cubes. One draw.", font=font(49, True), fill="#f2f5ff")
d.text((47, 136), "Same wave. Shared mesh. Per-instance positions.", font=font(18), fill="#97a7bd")
d.rounded_rectangle((1040, 42, 1232, 79), 18, fill="#152a35", outline="#30525e")
d.ellipse((1057, 56, 1067, 66), fill="#6ee7dc")
d.text((1080, 50), "bgfx / OpenGL", font=font(15), fill="#c7e7e6")
d.line((48, 730, 1232, 730), fill="#293446", width=1)
d.text((48, 751), "SPACE  pause     UP / DOWN  amplitude     R  reset     ESC  exit", font=font(15), fill="#a7b7cb")
d.text((1030, 751), "bgfx instancing", font=font(15), fill="#6ee7dc")
(out / "overlay.rgba").write_bytes(im.tobytes())

`build.sh`

#!/usr/bin/env bash
set -euo pipefail
cd -- "$(dirname -- "$0")"
: "${BGFX_SDK:?Set BGFX_SDK to the directory containing bgfx, bx, and bimg}"
bgfx_lib_dir="${BGFX_LIB_DIR:-$BGFX_SDK/bgfx/.build/linux64_gcc/bin}"
shaderc_path="${SHADERC:-$bgfx_lib_dir/shadercRelease}"
mkdir -p build
"${PYTHON:-python3}" make_overlay.py
for stage in vs_wave vs_instanced fs_wave vs_overlay fs_overlay; do
    shader_type=vertex
    if [[ "$stage" == fs_* ]]; then shader_type=fragment; fi
    "$shaderc_path" -f "shaders/$stage.sc" -o "build/$stage.bin" \
        --type "$shader_type" --platform linux -p 330 \
        --varyingdef shaders/varying.def.sc -i "$BGFX_SDK/bgfx/src"
done
read -r -a sdl_cflags <<< "$(pkg-config --cflags sdl3)"
read -r -a sdl_libs <<< "$(pkg-config --libs sdl3)"
g++ -std=c++20 -O2 -Wall -Wextra -Werror -fmax-errors=5 -DBX_CONFIG_DEBUG=0 \
    "${sdl_cflags[@]}" -I"$BGFX_SDK/bgfx/include" -I"$BGFX_SDK/bx/include" \
    main.cpp -o build/instanced-cubes \
    "$bgfx_lib_dir/libbgfxRelease.a" "$bgfx_lib_dir/libbimgRelease.a" \
    "$bgfx_lib_dir/libbxRelease.a" "${sdl_libs[@]}" -lX11 -ldl -lpthread -lrt

`verify_instancing.py`

"""Compare actual framebuffer pixels and draw counts, not estimated FPS."""
from pathlib import Path
import json
import re
import subprocess
from PIL import Image, ImageChops

root = Path(__file__).resolve().parent
build = root / 'build'
report = {}
images = {}
for name, time, amplitude in [('flat-0', 0, 0), ('flat-2', 2, 0), ('wave-0', 0, 1.35), ('wave-2', 2, 1.35)]:
    for mode in ['instanced', 'individual']:
        key = name + '-' + mode
        path = build / (key + '.ppm')
        args = [str(build / 'instanced-cubes'), '--frames', '8', '--time', str(time),
                '--amplitude', str(amplitude), '--screenshot', str(path)]
        if mode == 'individual':
            args.append('--individual')
        run = subprocess.run(args, check=True, capture_output=True, text=True, timeout=30)
        draws = int(re.search(r'last frame draws=(\d+)', run.stdout)[1])
        assert draws == (2 if mode == 'instanced' else 626), run.stdout
        assert ('Instanced frames=8' if mode == 'instanced' else 'individual frames=8') in run.stdout
        images[key] = Image.open(path).convert('RGB')
        assert images[key].size == (1280, 800)
        assert len(images[key].getcolors(1280*800) or []) > 100
        report[key] = {'draws_including_overlay': draws, 'stdout': run.stdout.strip()}
    delta = ImageChops.difference(images[name+'-instanced'], images[name+'-individual'])
    assert delta.getbbox() is None, f'{name}: rendering paths differ'
assert ImageChops.difference(images['flat-0-instanced'], images['flat-2-instanced']).getbbox() is None
changed = sum(max(pixel) > 8 for pixel in ImageChops.difference(images['wave-0-instanced'], images['wave-2-instanced']).getdata())
assert changed > 10000, changed
report['checks'] = {'four_pairs_pixel_identical': True, 'zero_amplitude_time_invariant': True, 'moving_wave_changed_pixels': changed}
(build/'instancing-validation.json').write_text(json.dumps(report, indent=2)+'\n')
print(json.dumps(report['checks']))

Build and run the saved files

Run these commands inside demo-instanced-cubes. Set PYTHON to an interpreter with Pillow installed.

export BGFX_SDK=/path/to/bgfx-sdk
export PYTHON=/usr/bin/python3
pkg-config --modversion sdl3
bash build.sh
./build/instanced-cubes

# Render the same scene with individual draws.
./build/instanced-cubes --individual

# Compare framebuffer images and draw counts under four fixed conditions.
"$PYTHON" verify_instancing.py

Space pauses, Up/Down change amplitude, R resets, and Esc exits. The verification script uses hidden windows but still requires access to X11 and OpenGL. It writes build/instancing-validation.json and fails if images differ or submission counts do not match expectations.

Clay Board Style System

Clay Board Style System is a foundation I am developing for native GUI toolkits, drawing on CSS concepts. This demo runs independently with C++ and SDL3 and does not use CBSS. If you want to combine GPU rendering with UI layout and input, see its bgfx adapter through bgfxim and the GPU host documentation.

Inside TypeScript 7: How the Compiler Finds Types You Never Wrote

puffball1567 — Sun, 11 Oct 2026 16:28:08 +0000

TypeScript can catch an invalid method call before your program runs, even when you never wrote a type annotation for the variable. Leaving types out is convenient, but what evidence does the compiler use to recover them?

TypeScript adds type syntax and checking to JavaScript. A type describes information the checker can use to decide which operations are valid for a value, such as treating it as a string or a number. In const age: number = 20, the : number is a type annotation explicitly describing age. Official introduction to variable annotations

The TypeScript compiler reads source code, checks type relationships, and can emit JavaScript. The component responsible for examining types is the type checker. This article reads that component in TypeScript 7's Go implementation. The TypeScript examples are the code being checked; the Go excerpts are the compiler code doing the checking.

You can start with familiarity with variables, functions, and return. Compiler terminology and the Go notation needed for each excerpt are introduced along the way. Rather than cover every form of inference, we will focus on one question: how does the compiler determine the type a function returns?

I am not part of the TypeScript team. This is an independent technical reading of the publicly available source code and documentation, not an official explanation of the implementation or its design decisions.

Source and license note

The source comes from Microsoft's public microsoft/TypeScript repository, primarily its Go compiler's checker.go and types.go. References are pinned to revision f29aeb9, with line links beside the implementation discussion.

The source is licensed under the Apache License, Version 2.0. Blocks labeled “upstream excerpt” quote that repository, with unrelated portions omitted and explanatory comments added. Diagrams, explanations, and learning examples in TypeScript were created for this article. The full license is available in LICENSE.txt; third-party attribution notices are available in NOTICE.txt.

Start with code that has no type annotations

There is no return type annotation here. There is no type annotation on user, either. Yet TypeScript knows that user.name is a string.

function getUser() {
  return { name: "Alice", age: 20 };
}

const user = getUser();
// name is a string, so this string method is available.
user.name.toUpperCase();

Here, getUser returns an object with two properties, name and age. The statement const user = getUser() calls the function and stores its result in user. The last line reads the name through user.name and calls toUpperCase() to convert that string to uppercase.

How does it know? The compiler does not run getUser() and inspect the result. It examines expressions and declarations in the source and constructs type information. This is type inference. The TypeScript Handbook describes return type inference as deriving a function's return type from its return statements.

This series reads widely used tools to find implementation patterns we can apply in our own software. This installment follows return type inference through TypeScript 7's Go compiler. You do not need to have read the previous article about checker pools: this one starts with the function above.

Four objects to keep apart

Before following function calls inside the compiler, we need a small map.

getUser() in the source
    |
    +-- AST        The syntax of calling the name getUser
    +-- Symbol     Information about the declaration that name refers to
    +-- Type       The type of the value being examined
    +-- Signature  Parameters and return information for a function call
                        +-- resolvedReturnType -> computed return Type

This is a map of responsibilities, not a diagram of four physically nested objects.

An AST, or abstract syntax tree, describes source structure: a function declaration, a return statement, an object literal. Recognizing that structure and determining its types are different jobs.

A Symbol connects a name to declaration information. The same text, getUser, can refer to different declarations in different scopes. The compiler must resolve the name at its particular location.

A Type represents information such as string, number, or an object type. A Signature describes a callable shape, including parameters and return information. Function types can have overloads, so a function type and a Signature are not interchangeable concepts. Our example has neither overloads nor parameters.

These roles appear in name resolution, call resolution, and the Signature definition.

From the name to the function being called

For getUser(), the compiler first needs to examine the expression being called: getUser. Inside resolveCallExpression, we find this line:

// Upstream excerpt: node represents the whole getUser() call.
// node.Expression() represents the getUser expression being called.
funcType := c.checkExpression(node.Expression())

c is a pointer to the Checker doing the work. The result is a *Type, a pointer to type information, not the runtime result of calling the function. In Go, := declares a variable and assigns its initial value. Source

A name such as getUser, used for a function or variable, is an identifier. Expression checking dispatches according to the kind of expression; checkIdentifier handles identifiers. Its role is to determine what declaration the name refers to and what type of value it represents. Identifier checking

To obtain the declaration information, checkIdentifier calls getResolvedSymbol. On the first request for this identifier's AST node, getResolvedSymbol uses resolveName to determine which declaration getUser refers to at this location. It stores a reference to the resulting Symbol in links.resolvedSymbol, associated with that node. Resolution and storage

Later requests in the same checker for the same identifier AST node return the stored reference. This is not a cache that treats every occurrence of the text getUser as identical. An identifier at another location is a different node, and its scope may lead to a different declaration.

The binder prepares the declaration information used by this lookup. Function declarations enter that process through bindFunctionDeclaration. Registering a declaration and resolving a name at its use site are the two sides of this connection. Function binding

At this point, we can distinguish “which function is this?” from “what does it return?” Answering the first question does not require that the second answer already be computed.

A Signature can exist before its return type is known

Here are the fields we need from the actual Signature structure:

// Upstream excerpt: other fields omitted.
type Signature struct {
    declaration        *ast.Node     // Points to the function declaration.
    parameters         []*ast.Symbol // A slice of parameter symbol pointers.
    resolvedReturnType *Type         // Computed return type; nil if not computed.
}

In this example, declaration points to the AST node representing function getUser() { ... }. It refers to an in-memory node created by parsing the source, not directly to a line number or a position in the source text. The node provides access to the parameters and body. The Signature does not contain a copy of the function's source. []*ast.Symbol is a slice of pointers to parameter symbols. Our getUser has no parameters. nil means that no type pointer has been stored in the return-type field yet. Structure definition

getSignatureFromDeclaration is the entry point for obtaining a declaration's Signature. On the first request, it collects parameter information and calls newSignature, passing nil for the as-yet-uncomputed resolvedReturnType. It stores the returned Signature pointer in links.resolvedSignature, associated with the declaration node. Later requests for the same declaration in the same checker return that stored pointer. Creation and storage, subsequent reuse

There is not one Signature for the entire compiler. For ordinary function declarations like this example, the declarations of getUser and getCount have separate Signatures. The beginning of getSignatureFromDeclaration shows how they are associated:

// Upstream excerpt: declaration is the function declaration being examined.
// Obtain the storage associated with this declaration node.
links := c.signatureLinks.Get(declaration)
if links.resolvedSignature != nil {
    // Return the Signature pointer previously stored for this declaration.
    return links.resolvedSignature
}

Passing the node to Get(declaration) selects declaration-specific information, not one shared slot for every function. When creation is needed, newSignature allocates a new Signature through sig := c.signatureArena.New(). Declaration-specific lookup, allocation

Two ordinary function declarations in the same checker

getUser declaration  -> its links -> resolvedSignature -> Signature A
getCount declaration -> its links -> resolvedSignature -> Signature B

Request getUser again -> return the stored Signature A

The sig in getReturnTypeOfSignature(sig *Signature) is a parameter name. It points to A in a call that receives A, and B in a call that receives B. Each call receives one of the available Signatures through that parameter. This describes our simple declarations, not a universal one-Signature-per-function rule: generic instantiation and other features can create additional Signatures.

newSignature allocates a Signature from the checker's signatureArena, stores the supplied declaration-node pointer and parameter information, and returns a pointer to that Signature. The field has type core.Arena[Signature]. Field definition, factory implementation

This is the same small core.Arena[T] implementation discussed in the earlier article about AST memory layout. It groups values of one type in Go slices, and New() returns a pointer to one element. Here, the type argument T is Signature. The AST allocator uses the same implementation, but the allocated objects and the arena instances are different. Arena implementation

For allocation details and pointer validity, see TypeScript 7 Arena Allocation and AST Memory Layout. Here, the important result is a Signature that refers to the function declaration and has no computed return type yet.

New Signature
  declaration        -> AST for function getUser() { ... }
  parameters         -> no parameters
  resolvedReturnType -> nil

After return type computation
  declaration        -> the same declaration AST
  resolvedReturnType -> Type representing { name: string; age: number }

Compute the return type when it is needed

checkCallExpression obtains the call's Signature through getResolvedSignature, then passes that Signature to getReturnTypeOfSignature. Call site

The return-type function starts with a cache lookup:

// Upstream excerpt: return the existing Type pointer if already computed.
if sig.resolvedReturnType != nil {
    return sig.resolvedReturnType
}

Here, sig points to the Signature being examined. If the field is empty, more work is needed. The ordinary declaration branch first looks for an explicit return type annotation, then examines the body if there is no annotation:

// Upstream excerpt: part of the default branch for ordinary declarations.
t = c.getReturnTypeFromAnnotation(sig.declaration)
if t == nil {
    if !ast.NodeIsMissing(sig.declaration.Body()) {
        t = c.getReturnTypeFromBody(sig.declaration, CheckModeNormal)
    } else {
        t = c.anyType
    }
}

t is a local *Type variable holding the result under computation. sig.declaration is the declaration saved earlier; Body() retrieves its body. CheckModeNormal selects ordinary checking. Our example has a body but no return annotation, so it takes the getReturnTypeFromBody path. Complete function

The real function also handles generic instantiation, composite signatures, optional calls, and circular resolution. This excerpt is not a replacement implementation. Nor does finding an annotation mean the compiler skips checking whether the body satisfies it: obtaining a return type and validating the body are different responsibilities.

Build the type from return expressions

For an ordinary block-bodied function, getReturnTypeFromBody calls checkAndAggregateReturnExpressionTypes. That helper visits return statements, extracts their expressions, checks them with checkExpressionCachedEx, and collects their types without duplicate entries. Return-expression collection

Our return expression is { name: "Alice", age: 20 }.

return { name: "Alice", age: 20 }
                 |           |
                 |           +-- numeric expression
                 +-------------- string expression
                 v
          construct object property types
                 v
          adjust the inferred return type
                 v
          { name: string; age: number }

Why is name a string rather than the type "Alice"? TypeScript also has literal types, which describe specific values. But this object's properties are mutable:

function getUser() {
  return { name: "Alice", age: 20 };
}

const user = getUser();
// const prevents reassigning user, not changing the object's properties.
user.name = "Bob";
user.age = 21;

Here, specific literal types are widened to string and number. This is literal widening. The implementation includes return-type widening and property-level widening for object literals. Annotations, context, and const assertions affect the result; literals do not always become their wider primitive types. Return-type adjustment, object-property widening

In getUser(), the type of name was string, allowing other strings such as "Bob". TypeScript can also express a type that accepts only the string "Alice". When "Alice" appears in a type annotation, it specifies that single-value type rather than a runtime string expression.

Add as const to preserve these specific types in the returned object:

function getFixedUser() {
  // Keep name as the type "Alice" and age as the type 20, without widening.
  // The properties of this object also become readonly.
  return { name: "Alice", age: 20 } as const;
}

const user = getFixedUser();
// : "Alice" means this variable accepts only the string "Alice".
// user.name has that type, so the assignment is valid.
const literalName: "Alice" = user.name;

The last line declares literalName and assigns user.name to it. The literalName: "Alice" part specifies the accepted type; = user.name supplies the value. It neither converts the value nor checks it at runtime. The compiler checks that the type on the right fits the annotation on the left.

Compare the two examples:

	`getUser()` without `as const`	`getFixedUser()` with `as const`
Type of `name`	`string`	`"Alice"`
Type of `age`	`number`	`20`
`user.name = "Bob"`	Passes type checking	Type error because the property is readonly

Readonly here is a TypeScript checking constraint: as const does not freeze the object at runtime. Also, const user prevents reassignment of the variable; it serves a different purpose from the as const assertion on the object. Official const assertion documentation

Inference determines not only that a value is a string, but also whether its specific value remains part of the type.

What if there are two return statements?

Consider a function whose return value depends on a condition:

function getValue(asText: boolean) {
  if (asText) {
    return "ready";
  }
  return 200;
}

const value = getValue(true);
// The return type is "ready" | 200. Narrow it before calling a string method.
if (typeof value === "string") {
  value.toUpperCase();
}

The return type is the union "ready" | 200: a value can have either type. These literal types are retained, unlike the mutable object properties in the earlier example. Passing true does not specialize this ordinary function's return type to "ready" at that call site. The call uses the return type inferred from the function body.

The helper we just followed returns ([]*Type, bool): the collected types and a flag used for cases that do not return a normal value. After handling that flag and empty return-type collections, its caller combines the collected types with getUnionTypeEx. Ordinary function-body branch

Reading only the first return statement would miss valid possibilities. Simulating the function with each call's runtime arguments is unnecessary, too. The compiler combines possible types, and the caller can narrow the result before using operations that require one particular type.

Where the inferred type is stored

At the end of getReturnTypeOfSignature, we find:

// Upstream excerpt: preserve a result already assigned during resolution.
if sig.resolvedReturnType == nil {
    sig.resolvedReturnType = t
}
return sig.resolvedReturnType

The destination is the field on the same Signature we started with. The returned pointer is the one stored in that field. The next request for this Signature's return type can take the early return at the top of the function. Storage and return

First request for the same Signature
  nil -> compute from the body -> store resolvedReturnType -> return it

Request after computation
  return resolvedReturnType

This combines lazy computation with memoization: compute information when needed, then retain the result. Ordinary checking may already have requested the return type before the compiler reaches a call you are looking at. This diagram describes a dependency between questions, not a promise about the compiler's global traversal order.

These Signatures are created on the checker side. The cache is not a promise to share one pointer across different checkers or future builds. It is a concrete example of the reusable semantic state discussed in the checker-pool article.

What if reassignment changes the type at a later location?

Caching alone might suggest that once a variable is treated as a number, every later use must treat it as a number too. But this code passes TypeScript checking:

// This variable accepts either a number or a string.
let value: number | string = 20;

// The assignment leading to this location supplied a number.
value.toFixed(0);

value = "hello";
// At this location, the assignment supplied a string instead.
value.toUpperCase();

Calling toFixed does not change the type of value. Initialization supplies a number, and the later assignment supplies a string. We need to distinguish the type a variable accepts from the type known at a particular reference to that variable.

Information	Type in this example	Purpose
Declared type	`number \	string`
`value` before `toFixed`	`number`	Determine valid operations at this location
`value` after reassignment	`string`	Determine valid operations at this location

The declared type remains number | string, so assigning a string is allowed. Assigning true would be a TypeScript error because it is outside that union; no ESLint rule is required. The compiler analyzes assignments and branches to narrow the type at individual locations through control flow analysis. Official explanation of assignments and narrowing

The Go implementation separates these concerns too. Inside checkIdentifier, we find:

// Upstream excerpt: obtain the type accounting for flow to this reference.
flowType = c.getFlowTypeOfReferenceEx(node, t, initialType, flowContainer, nil)

node identifies the particular reference to value being checked. t is the variable's underlying type, number | string in this example. initialType supplies the starting type for flow analysis, and flowContainer identifies its enclosing analysis scope. The final nil lets the function obtain the starting flow node from the reference rather than receiving one explicitly. The returned flowType is a *Type for this location. This call does not overwrite sig.resolvedReturnType. Call site, reference-based analysis

getFlowTypeOfReferenceEx follows the flow associated with the reference, accounting for assignments and branches. getTypeAtFlowAssignment checks whether an assignment targets the reference being analyzed and, for a declared union, reduces the type using the assigned type. This distinguishes the number assignment from the later string assignment. Assignment handling

What does this function return?
  Signature -> resolvedReturnType

What type is available at this variable reference?
  Variable's underlying type + assignments and branches -> type at this location

Reusing type information does not mean applying the first observed type of a variable to all later references. The information must match the subject and conditions of the query. Flow analysis also happens during compilation: it examines the source rather than monitoring values while the program runs.

Back to user.name.toUpperCase

We can now explain the opening example as a sequence of type questions:

getUser()
  -> resolve the call's Signature
  -> obtain { name: string; age: number }

const user = getUser()
  -> derive the variable's type from its initializer

user.name
  -> look up name on the object's type
  -> string

user.name.toUpperCase()
  -> check the call to the method available on string

The checker also retains computed variable types. Property access starts by checking the left-hand expression's type, then examines the requested property. Variable-type cache, property-access entry point

“Inference” covers several cooperating operations. Resolving a name, finding an expression's type, and looking up a property answer different questions. Keeping those questions separate makes the implementation easier to follow.

What happens when the source code is edited?

The previous example contained a reassignment within one version of the source. Now consider editing the function and checking the changed source again:

function getUser() {
  // Change the number 20 to the string "20".
  return { name: "Alice", age: "20" };
}

const user = getUser();
// @ts-expect-error age is now string, so the numeric method is unavailable.
user.age.toFixed(0);

@ts-expect-error is a comment that the TypeScript compiler interprets specially. The next line is still type-checked, but its type errors are suppressed. If that line has no type error, the compiler instead reports an unused @ts-expect-error directive.

With the directive present, the error about toFixed is suppressed and this example passes type checking. Delete the entire // @ts-expect-error ... line to see TS2339: toFixed does not exist on string.

In either case, user.age remains a string and the method call remains invalid. The directive does not fix the code; it lets the example check that an expected type error occurs. Executing the emitted JavaScript would still produce a runtime error at this call.

Does the previously cached number remain? We need to separate reusing a computed type inside a checker from deciding which previous build results remain valid after an edit. The nil check itself does not detect file changes.

The incremental builder tracks a file version, derived from its input, and a signature, which can be derived from declaration output. They help distinguish changes to the input from changes to the externally visible shape. This lowercase signature is a comparison string, not the Go Signature structure representing a function call. Change detection, shape-signature computation

age: 20 -> age: 21
  Source changes; this example's public age type remains number.

age: 20 -> age: "20"
  Source changes; its public age type changes from number to string.

That difference helps the builder find affected files. Declaration files, global declarations, compiler options, and saved state also affect its decisions. It is not a guarantee that unchanged public types prevent every dependent recheck. The relevant lesson here is that a cached inference result needs a separate mechanism to manage where it remains valid.

What to borrow for application code

The implementation separates identifying an object, computing information about it, and retaining the result on an appropriate owner. That pattern applies to parsed configuration, document analysis, and other derived information.

Lazy computation can avoid work on information nobody requests. Memoization can avoid repeating the same work. The trade-off is that we must handle circular computation and changes to the input. TypeScript's resolution checks and incremental builder provide concrete examples of those additional responsibilities.

The compiler knows that user.name is a string because name resolution, return-type computation, and property lookup connect the necessary facts. Understanding those steps explains both why annotations can be omitted and what information the compiler retains to answer later questions.

Example verification

The TypeScript examples were checked in strict mode with TypeScript 5.7.2, including declaration output for inferred types. Removing the expected-error comment produces TS2339 for toFixed. The union reassignment example was also emitted as JavaScript and executed with Node.js. Additional checks reject assigning a boolean and calling toFixed after string reassignment. The Go implementation discussion is based on the pinned source revision above; these checks are not a TypeScript 7 binary run or a performance measurement.

Related project

I develop Kinmokusei, a language with TypeScript-inspired syntax that generates Go code. Separating syntax processing from name and type handling is also a practical concern when building a language. Its documentation introduces the language and its syntax.

Object-Oriented Programming for Beginners: Build a Character Health System

puffball1567 — Sat, 03 Oct 2026 14:00:29 +0000

A game character takes 30 damage, reducing their health from 100 to 70. A variable and a subtraction can handle that. But what happens when there are two characters? Where should we handle damage that exceeds the remaining health, or a negative value passed by mistake?

This article introduces object-oriented programming through a small character health program. In this first installment, we will group data with operations, create separate characters from the same definition, and put the rules for changing health in one place.

The examples use Kinmokusei, a programming language I am developing. It uses TypeScript-inspired syntax and compiles to Go source code. We will explain the class and method syntax as we use it. You do not need prior Kinmokusei experience, but you should be familiar with variables, functions, and if statements.

We will start by managing HP with variables and a function, then gradually rewrite the program using a class. At the end of this article, you will find the complete program and instructions for running it.

Start with variables and a function

Begin with a character's name and current health:

const heroName = "Aki";
let heroHp: int = 100;

heroName holds the name; heroHp holds the current hit points, or HP. int means an integer. We use let for HP because we will assign a new value, and const for a name we do not reassign in this example.

We can put the damage calculation in a function:

function damage(hp: int, amount: int): int {
  if (amount <= 0) {
    return hp;
  }
  if (amount >= hp) {
    return 0;
  }
  return hp - amount;
}

hp is the current health, and amount is the damage. The final : int says the function returns an integer. Zero or negative damage leaves health unchanged; damage at least as large as the remaining HP returns zero. Otherwise, we subtract.

The function returns a new number. To update the caller's variable, assign that result:

heroHp = damage(heroHp, 30);
// heroHp is now 70.

With two characters, the code inside main might look like this:

const heroName = "Aki";
let heroHp: int = 100;
const partnerName = "Haru";
let partnerHp: int = 100;

heroHp = damage(heroHp, 30);
fmt.Println(heroName, heroHp);
fmt.Println(partnerName, partnerHp);

fmt.Println prints values so we can inspect them. The complete program later includes the import from Go's standard library. This example prints:

Aki 70
Haru 100

A function already lets us share the damage calculation without introducing a class. However, names and health values are separate variables. The caller keeps track of which values belong together. Writing partnerHp = damage(heroHp, 30) would assign a result based on the hero's health to the partner. Both values are integers, so their types alone cannot catch this mix-up.

Let's try grouping a character's name and health together, then asking that character to take damage.

Define a character with a class

An object, in this example, holds state such as a name and HP and offers operations using that state. A class defines what those objects hold and which operations they provide.

Start with a class named Character:

class Character {
  public name: string;
  private hp: int;

  constructor(name: string) {
    this.name = name;
    this.hp = 100;
  }
}

Variables belonging to an object, such as name and hp, are called fields. string represents text, and int represents an integer. public permits access from outside the class; private restricts access to the class's implementation. We expose the name while keeping health under the class's control. The public name field can also be changed from outside in this version.

constructor contains the initialization code that runs when an object is created. Here, it stores the supplied name in a field and sets HP to 100. This initialization mechanism is called a constructor.

this refers to the object being initialized or operated on. In this.name = name, the left side is the object's field; the right side is the constructor argument. Their names match, but they serve different roles.

new Character("Aki")
        |
        +-- constructor argument name receives "Aki"
                this.name = name  -> store the name "Aki"
                this.hp = 100     -> start at 100 HP

Create two separate instances

Writing class Character defines the type; it does not create the hero or partner. Use new to create actual objects:

const hero = new Character("Aki");
const partner = new Character("Haru");

An individual object created from a class is an instance of that class. hero and partner each refer to a Character instance. Calling new twice creates two characters, each with their own name and HP.

Character class
  Defines the name and HP fields
          |
          +-- new Character("Aki")  -> hero    -> Aki  / HP 100
          +-- new Character("Haru") -> partner -> Haru / HP 100

const means we cannot reassign the variable to a different object. It does not freeze the character's HP. Also, const other = hero would not create a new character: it would add another reference to the same one. The separate new calls are what create separate state.

Add methods that work on the character

Next, add the damage operation inside Character. A function defined on a class and called on an object is a method. Insert these two methods after the constructor, before the class's closing brace:

public function takeDamage(amount: int): void {
  if (amount <= 0) {
    return;
  }
  if (amount >= this.hp) {
    this.hp = 0;
    return;
  }
  this.hp = this.hp - amount;
}

public function getHp(): int {
  return this.hp;
}

takeDamage receives only the damage amount. The target object already holds its current health in this.hp. Its return type, void, means it does not return a value to the caller. Instead, it updates the object's state.

getHp returns the current HP as an integer. It lets callers inspect health without changing it.

To damage the hero, call:

hero.takeDamage(30);

The expression before the dot, hero, identifies the target. During this method call, this refers to the character referenced by hero. Only that character's health changes:

Before                             After hero.takeDamage(30)
hero    -> Aki  / HP 100            hero    -> Aki  / HP 70
partner -> Haru / HP 100            partner -> Haru / HP 100

The function version used heroHp = damage(heroHp, 30): pass in the current value and assign the result. The method version uses hero.takeDamage(30): identify an object and ask it to perform an operation. We can still call a method on the wrong character, but the relationship between a name, its HP, and the health-changing operation is now part of the program's structure.

Keep health changes within the rules

Why make hp private? Code outside the class cannot directly write:

// This is a compile error. Do not add it to the finished program.
hero.hp = -999;

Callers use hero.takeDamage(...) instead. That entry point applies these rules:

Damage amount	Action
Zero or negative	Leave HP unchanged
At least the remaining HP	Set HP to zero
Any other positive amount	Subtract it from HP

If a character has 70 HP and takes 200 damage, we compare before subtracting and set HP to zero. Subtracting a negative number would otherwise increase health, so the first condition returns without making a change. Starting at 100 in the constructor and updating only through this method keeps HP between 0 and 100.

Grouping state with the operations that manage it, and defining what callers can access, is encapsulation. Merely writing private does not automatically enforce a rule. The class must implement valid state changes and provide the operations through which callers use them.

This small program could also be designed with functions and separate data structures. The class expresses a particular grouping: whose state we are working with, and how that state may change. We can explore this part of object-oriented programming without introducing inheritance.

Save and run the complete program

Create a directory named character-health and save the following code as main.km. This assembles the pieces above and adds a main function to exercise them.

character-health/
└── main.km

import go fmt from "fmt" imports Go's standard formatting library. We use fmt.Println to print the results. Execution starts in main.

import go fmt from "fmt";

class Character {
  public name: string;
  private hp: int;

  constructor(name: string) {
    this.name = name;
    this.hp = 100;
  }

  public function takeDamage(amount: int): void {
    if (amount <= 0) {
      return;
    }
    if (amount >= this.hp) {
      this.hp = 0;
      return;
    }
    this.hp = this.hp - amount;
  }

  public function getHp(): int {
    return this.hp;
  }
}

function main(): void {
  const hero = new Character("Aki");
  const partner = new Character("Haru");

  fmt.Println(hero.name, hero.getHp());
  fmt.Println(partner.name, partner.getHp());

  hero.takeDamage(30);
  fmt.Println("After 30 damage:", hero.name, hero.getHp());
  fmt.Println("Partner:", partner.name, partner.getHp());

  hero.takeDamage(200);
  fmt.Println("After 200 damage:", hero.name, hero.getHp());

  hero.takeDamage(-10);
  fmt.Println("After negative damage:", hero.name, hero.getHp());
}

Follow the official installation guide to install Kinmokusei's CLI and its supported Go toolchain. The CLI is named keika. From character-health, run:

keika version
keika check main.km
keika run main.km

check validates the source; run compiles and executes it. I ran this sample with keika v0.4.3 and go1.23.5 linux/amd64, producing:

Aki 100
Haru 100
After 30 damage: Aki 70
Partner: Haru 100
After 200 damage: Aki 0
After negative damage: Aki 0

Both characters start at 100 HP. After the hero takes 30 damage, their HP becomes 70 while the partner stays at 100. Another 200 damage reduces the hero's HP to zero, and the negative damage leaves it at zero. The output makes both independent instance state and the update rules visible.

Try changing hero.takeDamage(30) to partner.takeDamage(30). Which character's HP changes now? Then test damage amounts of 0, 100, and 101 on a newly created character with 100 HP to exercise the different branches.

Connect the vocabulary to the code

Term	Meaning in this program
Class	`Character`, the definition of state and operations
Object or instance	An individual character created with `new Character(...)`
Field	State held by each character, such as `name` or `hp`
Constructor	`constructor`, which sets the name and initial HP
Method	An operation called on a character, such as `takeDamage` or `getHp`
Encapsulation	Restricting direct HP access and updating it through defined operations

Adding healing gives us a next step. If healing must not exceed maximum HP, what state should the character hold, and where should that check live? Before scattering conditions across callers, try expressing healing as another operation the character provides.

Build a Colorful Wave of Cubes on the GPU with bgfx

puffball1567 — Fri, 02 Oct 2026 16:06:25 +0000

GPU Implementation with bgfx is a series about building a variety of GPU effects and techniques with bgfx. We'll start with small, working demos and explore animated shapes, drawing many objects efficiently, image effects, and GPU computation. Each article will connect what you see on screen to the code that makes it happen, explaining how the CPU and GPU share the work along the way.

For this first installment, let's make something move.

The scene below contains a 25 × 25 grid of cubes. Waves travel through the grid, lifting the cubes and shifting their colors. The CPU places the cubes on a flat grid; a vertex shader calculates their vertical movement on the GPU.

This is a capture of the working demo, not a mockup. Press Space to pause, Up/Down to change the amplitude, and R to reset it.

We'll build this effect step by step using bgfx's public API. You need some C++ familiarity, but no previous shader experience. The full demo source and build instructions accompany the article; the snippets below come from that implementation, with surrounding setup omitted where stated.

Representing 3D shapes with polygons

The scene shows cubes, but our program does not simply ask the GPU to “draw a cube here.” We describe the cube's surface as smaller faces and supply their positions and connections. Let's look at how that representation works.

A polygon is a shape with straight sides. Triangles and quadrilaterals are both polygons; in this demo, we divide every surface into triangles. Three points that do not lie on a straight line define one flat face. With four or more points, the points might not all lie in the same plane. This makes triangles a convenient building block for 3D surfaces, and they are the units used by our drawing setup.

To describe one square face of a cube, split it along a diagonal. Here is that face viewed straight on. The numbers 0 through 3 identify its corner points:

3 -------- 2
|        / |
|      /   |
|    /     |
|  /       |
0 -------- 1

Triangle A: 0 → 1 → 2
Triangle B: 0 → 2 → 3

Together, the triangles cover the whole square without a gap. The diagonal shows where we split the surface; it does not need to appear as a visible line. A cube has six square faces, so 6 faces × 2 triangles = 12 triangles describe its entire surface. We do not need to fill its interior with smaller cubes. Drawing the surface and using depth to determine which face is in front gives it a solid appearance.

Each corner point is a vertex. In 3D, its position is described by three numbers: (x, y, z). Their reference point is the origin, at (0, 0, 0).

Let's establish the axis directions used in this demo. Imagine looking horizontally toward the origin from the negative-Z side. From that reference viewpoint, the directions are:

Axis	Positive direction (increasing values)	Negative direction (decreasing values)
X	Right	Left
Y	Up	Down
Z	Away from you, beyond the origin	Toward you

For example, (1, 0, 0) is one unit from the origin along positive X, (0, 1, 0) is one unit up, and (0, 0, 1) is one unit along positive Z. X and Z describe positions along the ground plane; Y describes height. These are this demo's conventions, not rules shared by every 3D application.

The actual demo camera looks at this space from above and at an angle, so positive X does not necessarily point directly right on screen. “Right, up, and away” in the table describe our reference viewpoint. Moving the camera does not change the axes in the scene. The cube's vertex coordinates will use its own center as the origin, while positions used to arrange the cubes will use the center of the entire grid. We do not rotate the cubes in this demo, so the axis directions in these two coordinate systems stay aligned.

Positions alone do not tell us which points form a face, so we also supply connections: “use 0, 1, and 2 for one triangle; use 0, 2, and 3 for another.” A shape represented by vertices and their face connections is called a mesh. We will prepare one cube mesh.

Curved surfaces, such as spheres and characters, can also be approximated with many triangles. Our cube's faces are flat, so just two triangles per face describe their shape. This small mesh will be our starting point for drawing and animation on the GPU.

What runs on the CPU, and what runs on the GPU?

Our program has three pieces:

CPU / C++
  Upload one cube mesh during initialization
  Each frame: supply time, amplitude, and a position for each cube
       |
       v
GPU / vertex shader
  Calculate the wave height at that cube's center
  Move each corner upward or downward by that height
  Transform the result into clip space
       |
       v
Rasterization → GPU / fragment shader
  Color the covered fragments and shade the cube faces
       |
       v
Depth testing and color output → window

A vertex shader calculates where each mesh vertex goes for drawing. The GPU assembles triangles from the resulting vertices and the supplied connections. Rasterization determines which screen pixels those triangles cover: it connects the faces described by coordinates to the grid of pixels that makes up the image. A fragment shader then calculates color for the covered samples. Depth testing also determines visibility, so a hidden face's color does not simply appear on screen.

The shaders in this project use bgfx's GLSL-like shader language and are compiled with its shaderc tool. bgfx shader tooling

We will reuse one mesh, but submit a separate draw for each cube. This makes the connection between a cube's position and its shader inputs easy to follow. It does not make 625 cubes a single draw call. Instancing is a useful next step once this version works.

1. Project directory structure

We will organize the program in a directory named demo-wave-cubes, separating the C++ code from the shaders that run on the GPU:

demo-wave-cubes/
├── main.cpp              window, mesh, input, drawing loop
├── demo_support.h        vertex types and shader-loading helpers
├── build.sh              shader and C++ build commands
├── make_overlay.py       generate the transparent title/help image
└── shaders/
    ├── vs_wave.sc        vertex shader for wave displacement
    ├── fs_wave.sc        color, lighting, edge accents
    ├── varying.def.sc    vertex inputs and shader-stage connections
    ├── vs_overlay.sc    vertex shader for positioning the title image
    └── fs_overlay.sc    fragment shader for drawing the title image

main.cpp will prepare the geometry and draw inputs; the shaders in shaders/ will calculate the cubes' movement and color. The title and keyboard help will use a transparent image generated by make_overlay.py.

Building the project will generate the executable, compiled shaders, and overlay image in build/. We will cover the build and run commands after the implementation. First, let's prepare the geometry for one cube.

2. Describe one cube

First, define what one vertex contains. This is the actual type in demo_support.h, included by main.cpp:

struct Vertex { float x, y, z, nx, ny, nz; };

x, y, and z are the local position. nx, ny, and nz describe a normal: a direction pointing out of the face, used later for lighting. The top face has the normal (0, 1, 0); the face pointing along positive X has (1, 0, 0).

The demo creates four vertices for each of six faces: 24 vertices in total. A geometric cube has only eight corners, but one corner belongs to three faces with different normals. Keeping separate vertex records gives each face a flat appearance.

We encode the connections from the diagram as indices: numbers that refer to entries in the vertex array, starting at zero. In our drawing setup, each group of three indices specifies one triangle. For the first face:

Four face vertices: 0, 1, 2, 3
First triangle:    0, 1, 2
Second triangle:   0, 2, 3

6 faces × 2 triangles × 3 indices = 36 indices

The first face's index array is {0, 1, 2, 0, 2, 3}. Both triangles refer to vertices 0 and 2, so they reuse those vertex records within the face. The next face has four separate vertices and uses {4, 5, 6, 4, 6, 7}. Repeating this for all six faces gives the demo's 36 indices. 24 counts vertex records, 12 counts triangles, and 36 counts references to vertices; these numbers describe different things.

main.cpp fills std::vector<Vertex> vertices and std::vector<uint16_t> indices with that data. Then it describes the vertex layout and creates the buffers:

bgfx::VertexLayout layout;
layout.begin()
    .add(bgfx::Attrib::Position, 3, bgfx::AttribType::Float)
    .add(bgfx::Attrib::Normal, 3, bgfx::AttribType::Float)
    .end();

// Copy the CPU arrays into memory managed by bgfx.
auto vb = bgfx::createVertexBuffer(
    bgfx::copy(vertices.data(), uint32_t(vertices.size() * sizeof(Vertex))),
    layout);
auto ib = bgfx::createIndexBuffer(
    bgfx::copy(indices.data(), uint32_t(indices.size() * sizeof(uint16_t))));

Vertex stores six floats in this order: x, y, z, nx, ny, nz. The vertex buffer receives their bytes, without the C++ member names. We therefore need to tell bgfx which part represents a position and which part represents a normal. layout describes how to read that data.

The first .add(bgfx::Attrib::Position, 3, bgfx::AttribType::Float) says, “read the first three floats as a position.” The next .add(bgfx::Attrib::Normal, 3, bgfx::AttribType::Float) says, “read the next three floats as a normal.” Here, 3 counts the components of one position or direction, not the number of vertices. begin() starts the layout definition, and end() finalizes it.

One vertex:    [ x, y, z   | nx, ny, nz ]
Layout meaning:[ position | normal     ]
Shader input:  [ a_position| a_normal   ]

For example, a vertex on the top face might contain {0.46f, 0.46f, 0.46f, 0.0f, 1.0f, 0.0f}. The first three values become the position (0.46, 0.46, 0.46), and the last three become the upward normal (0, 1, 0). Our shader receives them through inputs named a_position and a_normal. This also connects to the POSITION and NORMAL definitions in varying.def.sc, which we will examine later.

In this build, a float occupies four bytes: 12 bytes for the position and 12 for the normal, making 24 bytes per vertex. The layout also records this distance from one vertex to the next, called the stride. With multiple vertices in the buffer, the same reading pattern repeats every 24 bytes.

That is why createVertexBuffer receives both the data and layout: the data supplies the numbers, and the layout describes their arrangement and meaning. The layout does not rearrange the numbers, so the order and types in the .add() calls must match the actual Vertex records.

vb is a bgfx::VertexBufferHandle; ib is a bgfx::IndexBufferHandle. They identify resources managed by bgfx. They are not pointers into the vectors. bgfx::copy copies the supplied bytes, so their later use does not depend on keeping the vectors' backing storage alive. Buffer and memory API

These buffers are created once, before the frame loop. Every cube uses them.

3. Give each cube a position

The previous section prepared one cube centered at (0, 0, 0). We will reuse that shape to make a grid of 25 by 25 cubes: 625 in total. Recall our reference directions: X is left/right, Z is depth, and Y is height.

Start with grid indices

Number the positions from 0 to 24 along both X and Z. The code calls these integer grid indices x and z. They are not yet coordinates measuring distance in the scene.

For example, (x, z) = (0, 0) selects the first position along both directions. (12, 12) selects the middle. Counting from zero makes index 12 the thirteenth position, the middle of 25 positions.

Each dot in the upper diagram is a cube center. Viewed from above, X runs across the page and Z runs up the page; Y is perpendicular to it. This is a different viewpoint from the demo's angled camera.

Turn each index into a center position

Using the indices directly as coordinates would place all cubes on the positive side of the origin. Subtract 12 to center the grid around zero:

Index:            0    1   ...   12   ...   23   24
Subtract 12:    -12  -11   ...    0   ...   11   12

Then multiply by the center spacing, 1.12. Each cube extends from -0.46 to +0.46 on each axis, making its side length 0.92. Spacing the centers by 1.12 leaves a gap of 1.12 - 0.92 = 0.20 between adjacent faces before displacement. This spacing is our design choice, not a bgfx constant.

Here is the calculation along X. The same calculation applies to Z.

Grid index `x`	Center around zero: `x - 12`	Center X: `(x - 12) * 1.12`
0	-12	-13.44
11	-1	-1.12
12	0	0.00
13	1	1.12
24	12	13.44

Grid indices (13, 12) therefore give the cube center (1.12, 0, 0). Indices (12, 13) give (0, 0, 1.12). For now, every center's Y coordinate stays zero.

Move the whole cube to that position

Moving every vertex by the same amount is called translation. To place the center at (1.12, 0, 0), add 1.12 to every vertex's X coordinate:

Vertex within cube       Translation       Vertex in scene
(0.46, 0.46, 0.46)   +  (1.12, 0, 0)  =  (1.58, 0.46, 0.46)

The lower diagram shows the center and the rightmost vertex moving by the same amount. Applying the same translation to every vertex preserves the cube's shape and size.

We describe this operation to the shader with a model matrix. A matrix is a rectangular arrangement of numbers; in 3D graphics, matrices represent operations such as translation, rotation, and scaling. Here we only translate. Coordinates relative to the cube's own center are called local coordinates; coordinates in the scene containing the entire grid are world coordinates. Our model matrix describes the conversion from local to world coordinates.

Inside the per-cube drawing loop, the implementation uses:

// x and z are grid indices, each ranging from 0 to 24.
float model[16];
bx::mtxTranslate(model, (x - 12) * 1.12f, 0.0f, (z - 12) * 1.12f);
bgfx::setTransform(model);

model is an array of 16 floats holding a 4 × 4 matrix. bx::mtxTranslate writes the matrix into its first argument, model. The next three arguments specify the X, Y, and Z translation. We do not need to calculate the individual matrix entries ourselves.

bgfx::setTransform(model) sets the matrix for the draw we will submit next. This call alone does not draw a cube. We will pair it with bgfx::submit later, and the vertex shader will use the matrix to calculate each vertex's position. The original vertex buffer stays unchanged.

Repeating this setup and drawing the shared cube inside the nested x and z loops fills the grid. So far, the CPU has only arranged the cubes on a flat plane. Next, we will pass time to the GPU and add the vertical wave motion.

4. Pass time into the shader

A uniform supplies a value that stays the same across a draw. We need a clock and an amplitude, so one four-component float value is enough.

Create its handle once, beside the buffers:

auto uWave = bgfx::createUniform("u_wave", bgfx::UniformType::Vec4);

Then fill its values during each frame:

// time is elapsed seconds; amplitude starts at 1.35.
const float wave[4] = {time, amplitude, 0.0f, 0.0f};

// Set this before each cube's submit; the final two components are unused.
bgfx::setUniform(uWave, wave);

The corresponding shader declaration is:

uniform vec4 u_wave;

The name u_wave connects the C++ uniform with the shader declaration. Its .x component carries time and .y carries amplitude. Pausing freezes the C++ clock; the shader continues rendering with the same input values. Uniform API

5. Calculate the wave at the cube's center

Here is the movement calculation from vs_wave.sc:

// A local origin transformed by the model matrix is the cube's center.
vec3 center = mul(u_model[0], vec4(0.0, 0.0, 0.0, 1.0)).xyz;
float radius = length(center.xz);
float height = u_wave.y * (
    sin(radius * 0.65 - u_wave.x * 1.8)
    + 0.35 * cos(center.x * 0.5 + center.z * 0.35 + u_wave.x));

u_model[0] is bgfx's predefined model matrix, populated through setTransform. .xz selects the two horizontal coordinates, and length measures their distance from the grid's center. Predefined uniforms

Read the first wave as three controls:

radius * 0.65 changes the phase as we move outward, producing rings.
-time * 1.8 shifts those rings over time.
amplitude controls the vertical distance traveled.

The smaller cosine wave adds variation across X and Z, so the result is not perfectly circular. These coefficients are artistic choices in this demo, not physical constants.

For a concrete check, put the center at (0, 0, 0) and time at zero. The sine term is zero and the cosine term is one, so the height is 1.35 × 0.35 = 0.4725. Setting amplitude to zero makes the height zero everywhere.

Why use the center, rather than the current vertex position? All corners of a cube need the same displacement. Sampling the wave separately at each corner would deform the cube. Here, every vertex invocation for a given cube independently calculates the same height, keeping it rigid.

6. Move each vertex and project it

Next, the shader transforms the actual corner and adds that height:

vec3 world = mul(u_model[0], vec4(a_position, 1.0)).xyz;
world.y += height;
gl_Position = mul(u_viewProj, vec4(world, 1.0));

a_position comes from the vertex buffer. world is the position after placing that cube in the grid. u_viewProj combines the camera view and projection; gl_Position is the clip-space output consumed by the graphics pipeline.

The CPU creates the camera matrices once because this demo has a fixed camera:

float view[16], projection[16];
bx::mtxLookAt(view, {27.0f, 25.0f, -32.0f}, {0.0f, 0.0f, 0.0f});
bx::mtxOrtho(projection, -25.0f, 25.0f, -11.82f, 11.82f,
    0.1f, 120.0f, 0.0f, bgfx::getCaps()->homogeneousDepth);
bgfx::setViewTransform(0, view, projection);

An orthographic projection keeps the grid's distant cubes from shrinking with perspective, which suits this graphic, diagram-like composition. View 0 is the scene's drawing group. The title overlay uses a separate view.

7. Give the wave color and depth

The vertex shader passes three values onward: the world position, the face normal, and the original local position. varying.def.sc declares the connection between the shader stages:

vec3 a_position : POSITION;
vec3 a_normal : NORMAL;
vec3 v_normal : TEXCOORD1;
vec3 v_world : TEXCOORD2;
vec3 v_local : TEXCOORD3;

This excerpt shows the wave inputs and outputs; the complete file also contains the overlay's UV coordinates. Here TEXCOORD1, for example, identifies an interpolated data channel. It does not require a texture. The vertex shader assigns v_normal = a_normal, v_world = world, and v_local = a_position; the fragment shader receives interpolated values across each triangle.

In fs_wave.sc, three offset cosine curves produce the red, green, and blue components:

float phase = v_world.x * 0.022 + v_world.z * 0.018 + v_world.y * 0.055;
vec3 color = 0.55 + 0.45 * cos(6.2831853 *
    (vec3(phase, phase, phase) + vec3(0.02, 0.35, 0.65)));

The phase depends on height as well as horizontal position. That makes a cube change color as it rises and falls, without uploading a new per-cube color from C++.

For lighting, compare the surface direction with one fixed light direction:

float light = 0.32 + 0.68 * max(dot(normalize(v_normal),
    normalize(vec3(-0.45, 0.85, -0.55))), 0.0);

The dot product grows as the two normalized directions align. max(..., 0.0) prevents negative lighting, while 0.32 keeps the unlit faces visible. This is a simple directional-light effect, with no cast shadows. Since our model matrices only translate, the normals remain valid as supplied. Adding rotation or nonuniform scaling would require transforming the normals too.

The full shader also adds a narrow bright accent near each face edge. It measures how close the local position is to two cube boundaries. This makes the cubes easier to separate visually; it does not add bevel geometry, bloom, or a physical material simulation.

8. Submit the same mesh with different inputs

The program handle is created before the frame loop by our own loadProgram helper in demo_support.h. It reads vs_wave.bin and fs_wave.bin, creates a shader from each with bgfx::createShader, and combines them using bgfx::createProgram(v, f, true). The full helper checks failures; the final true transfers responsibility for releasing those shader references to the program.

With the resources ready, the inner draw loop is:

// model and wave are the values constructed in the preceding steps.
bgfx::setTransform(model);
bgfx::setVertexBuffer(0, vb);
bgfx::setIndexBuffer(ib);
bgfx::setUniform(uWave, wave);
bgfx::setState(BGFX_STATE_WRITE_RGB | BGFX_STATE_WRITE_A |
               BGFX_STATE_WRITE_Z | BGFX_STATE_DEPTH_TEST_LESS);
bgfx::submit(0, program);

The first 0 in setVertexBuffer selects vertex stream zero; the 0 in submit selects view zero. They name different things. Depth writing and testing keep a farther cube from painting over a nearer one. This introductory mesh disables face culling; adding consistent winding and culling is a separate improvement.

After all cube draws and the overlay draw, call:

bgfx::frame(); // Advance the frame after recording this frame's drawing work.

The next frame supplies a new time. We never rebuild or upload the cube mesh to animate the wave. The CPU still builds matrices and records separate draws; moving an equation into a shader does not remove submission overhead. Drawing API

9. Build and run the source

With the implementation assembled, we can build the source and see it in motion.

The accompanying build targets Linux, SDL2/X11, and bgfx's OpenGL backend. XWayland also works in the environment used here. It uses a bgfx API 159 SDK with matching bx/bimg libraries and shaderc, plus a C++20 compiler. Other backends need matching shader binaries and platform setup; this particular build does not select them automatically.

Prepare the SDK and other dependencies using the README's build instructions, then run these commands from demo-wave-cubes:

# The directory must contain bgfx/, bx/, and bimg/.
export BGFX_SDK=/path/to/bgfx-sdk
bash build.sh
./build/wave-cubes

build.sh compiles the shaders and generates the overlay image and C++ executable. Running ./build/wave-cubes opens the animated field of 625 cubes. Press Space to pause, Up/Down to change the amplitude, R to reset, and Esc to exit.

Check the effect instead of trusting the picture

The supplied validation script renders screenshots through bgfx, then compares their pixels. It checks that a zero-amplitude field stays unchanged when time changes, and that a nonzero-amplitude field does change. The capture path reads this application's framebuffer, not the desktop.

The demo was built and exercised on Linux with SDL 2.0.20 and a bgfx API 159 SDK. bgfx reported OpenGL 4.3; the display's driver reported an accelerated AMD RENOIR device with Mesa 23.2.1. The six-second capture contains 180 frames sampled at a fixed 1/30-second simulation step. That is an animation export setting, not a measured performance claim.

Try changing just one term:

Set amplitude to zero to recover the flat grid.
Remove the cosine term to see only circular waves.
Increase 0.65 to fit more rings into the same space.
Remove the Y term from the color phase to keep the color field stationary.

Rebuild after changing a shader. Its .sc source is compiled into a .bin asset; editing the source alone does not replace the binary loaded by the application.

Where to take it next

We now have a small effect with a clear division of work: C++ supplies shared geometry and draw inputs, the vertex shader supplies movement, and the fragment shader supplies appearance.

The next practical question is how to draw this grid with fewer CPU submissions. A follow-up can replace the per-cube draw loop with instance data while preserving the same wave equation. After that, render targets and compute shaders open up effects that need intermediate images or persistent simulation state.

Clay Board Style System

Clay Board Style System is my CSS-inspired foundation for native GUI toolkits. It includes an optional GPU host and a bgfx adapter through bgfxim, connecting custom GPU content with native layout and input. If you want to take shader experiments into an application UI, see its GPU host documentation.

Inside TypeScript 7: Parallel Type Checking Without Giving Up Determinism

puffball1567 — Mon, 21 Sep 2026 19:32:09 +0000

A source-guided look at checker pools, import-graph partitioning, and the trade-off between build speed and duplicated type state

TypeScript 7 is often introduced as the Go-based, much faster successor to the JavaScript compiler. That description is true, but it misses one of the more interesting engineering decisions in the new compiler: type checking is not simply dispatched to an arbitrary worker pool. The compiler builds a fixed set of checkers, assigns source files to them deliberately, and keeps that assignment stable for a given program and checker count.

This matters because a type checker is not a stateless function that can examine any file in isolation. A file may rely on declarations from its imports, ambient declarations, generic instantiations, and the global scope. A design that maximized CPU use without considering those relationships would recreate the same semantic work repeatedly, make memory use unpredictable, and risk output whose ordering changes from build to build.

The TypeScript team describes TypeScript 7 as a native Go port which performs parsing, type checking, and emitting in parallel. Its public controls include --checkers, --builders, and --singleThreaded. This article focuses on the less obvious one: the type-checker pool used within a project.

Source and license note

This article discusses the publicly available microsoft/TypeScript repository. TypeScript 7’s Go compiler lives under tsc/; the earlier typescript-go staging repository was archived after the release. The source is licensed under the Apache License, Version 2.0.

The short blocks labelled as excerpts are from that repository. Diagrams, explanations, and the simplified code are original. The full sources discussed here are checkerpool.go and program.go. The repository’s NOTICE file remains available with its attribution notices.

The problem: type checking has shared semantic work

Parsing is comparatively easy to parallelize. Given a file’s text and compiler options, a parser can normally construct that file’s syntax tree without waiting for the rest of the program. Emitting JavaScript can often follow the same pattern.

Type checking is different. Consider a small project:

src/api.ts ───────┐
                   ├── src/service.ts ─── src/app.ts
src/models.ts ────┘

Consider the following code. ApiResponse<T> is generic: when the compiler checks ApiResponse<User>, it has to work with a concrete form in which T is replaced by User. This is called generic instantiation.

// src/models.ts
export type User = {
  id: string;
  name: string;
};

// src/api.ts
export type ApiResponse<T> = { data: T };

export async function request<T>(path: string): Promise<ApiResponse<T>> {
  // The real HTTP work is omitted to keep this example focused.
  throw new Error(`not implemented: ${path}`);
}

// src/service.ts
import { request } from "./api";
import type { User } from "./models";

export async function loadDisplayName(id: string): Promise<string> {
  const response = await request<User>(`/users/${id}`);
  return response.data.name.toUpperCase();
}

// src/app.ts
import { loadDisplayName } from "./service";

void loadDisplayName("123").then(console.log);

To check service.ts, a checker first resolves the names request and User to the modules that export them. To check request<User>(...), it handles the return type Promise<ApiResponse<User>>, in which T has been replaced with User. To confirm that response.data.name is valid, it must also follow User far enough to find name: string. app.ts imports loadDisplayName, so it also needs the exported function type.

In this article, semantic state means the checker’s internal working information: resolved names, compared types, and concrete types created from generics. It is neither emitted JavaScript nor a user-visible value. It is work the compiler can retain so that it does not have to answer the same type question repeatedly.

That gives file assignment a concrete trade-off.

One new checker per file

checker A: api.ts       → builds state for ApiResponse<T> and request<T>
checker B: models.ts    → builds state for User
checker C: service.ts   → may build its own state while following the imports
checker D: app.ts       → may separately follow the exported loadDisplayName type

Benefit: file-level work is easy to isolate
Cost: semantic state about shared imports can be duplicated

One checker for every file

checker 0: api.ts, models.ts, service.ts, app.ts

Benefit: symbols and types from imports are easier to reuse within one checker
Cost: one checker cannot safely serve multiple file checks at once, so file-oriented checking becomes effectively serial

The useful design space lies between those extremes: keep related files near the same checker where possible, while ensuring that no one checker receives most of the work.

Several checkers

checker 0: api.ts, models.ts, service.ts
checker 1: app.ts

service.ts stays close to the api.ts and models.ts files it imports, which aims to reuse checker 0's state.
app.ts is related to service.ts too, but the whole project must also avoid concentrating too much work in one checker.

The real compiler is not deciding only among these four files. It uses the complete import graph and an estimated weight for each file. It therefore does not follow a simplistic “always place an import beside its importer” rule; it looks for an assignment that preserves both useful locality and practical parallelism.

A checker is a stateful worker, not just a goroutine

In TypeScript 7, a checker pool owns a fixed number of *checker.Checker values, one mutex per checker, and a mapping from each source file to its assigned checker.

// Excerpt. Fields unrelated to this article are omitted; inline comments are explanatory.
type checkerPool struct {
    program          *Program                              // The Program for the project currently being compiled.
    checkers         []*checker.Checker                    // An ordered list of created checkers.
    locks            []*sync.Mutex                         // A mutex for the checker at the same index.
    fileAssociations map[*ast.SourceFile]*checker.Checker  // A lookup from file to its assigned checker.
}

First, a quick guide to the Go notation: *T is a pointer to T. Here it refers to one existing Program or Checker instance without copying it. []T is an ordered list, and map[K]V is a lookup table from keys of type K to values of type V. Therefore, []*checker.Checker is an ordered list of pointers to checkers, while map[*ast.SourceFile]*checker.Checker looks up a pointer to a checker from a pointer to a source file.

Each field has a distinct role.

Here, a mutex is short for mutual exclusion. It is a lock that prevents one shared resource from being changed simultaneously, or read while another operation is midway through changing it. When a goroutine calls mutex.Lock(), only one goroutine can hold that mutex. Another goroutine that calls Lock() on the same mutex waits until the first calls Unlock(). A mutex does not copy or store data; it decides who is currently allowed to use one checker.

program represents the one project currently being compiled. Program holds project-wide information such as source files, compiler options, and import relationships. The checker pool is not a global pool shared by every compilation; it is created to type-check this Program.
checkers is the list of objects that actually perform type checking. With two checkers, checkers[0] and checkers[1] hold different Checker instances. Each instance has its own caches for symbols, types, and generic instantiations.
locks is the list of mutexes that prevents two goroutines from using the same checker at once. The index relationship matters: locks[0] protects only checkers[0], and locks[1] protects only checkers[1]. This is not one global lock, so work using a different checker does not have to wait.
fileAssociations records the owner of every source file. Its key is *ast.SourceFile and its value is *checker.Checker. After service.ts is assigned to checker 0, fileAssociations[serviceFile] returns the same checker as checkers[0].

For the earlier project with two checkers, the relationship looks like this in principle:

checkers[0] = checker 0                  locks[0] = mutex for checker 0
checkers[1] = checker 1                  locks[1] = mutex for checker 1

fileAssociations[service.ts] ──────────> checker 0
fileAssociations[api.ts]     ──────────> checker 0
fileAssociations[models.ts]  ──────────> checker 0
fileAssociations[app.ts]     ──────────> checker 1

The important point is that locks belong to checkers, not to files. service.ts, api.ts, and models.ts are different files, but all are associated with checker 0. Any work using checker 0's state needs the same locks[0]. app.ts, associated with checker 1, uses locks[1] instead.

Within one Program, one file cannot use both locks[0] and locks[1]. fileAssociations[serviceFile] returns one checker, and that checker has one position in checkers and therefore one corresponding mutex. The mutex protects the checker's caches and in-progress state, which several files can share; it does not protect a file itself.

The following simplified Go code shows only how the mutex works. Treat work as type-checking one file with one checker. This is explanatory code, not the TypeScript implementation.

// withExclusiveChecker makes one checker exclusive for the duration of work.
func withExclusiveChecker(lock *sync.Mutex, work func()) {
    lock.Lock()         // Another goroutine using this lock waits until Unlock.
    defer lock.Unlock() // Release the checker even if work returns early.

    work() // Safely use the checker's caches and semantic state.
}

defer is Go syntax for running a call when the function exits. Here, it makes sure that Unlock() is not forgotten whether work completes normally or returns early. In the following examples, the go prefix starts a function call in a new goroutine.

This is permitted parallel work. The two jobs use different checkers and therefore different mutexes, so neither waits for the other.

// Explanatory pseudocode: service.ts uses checker 0; app.ts uses checker 1.
go withExclusiveChecker(locks[0], func() {
    typeCheck(checkers[0], serviceFile) // Uses only checker 0's state.
})

go withExclusiveChecker(locks[1], func() {
    typeCheck(checkers[1], appFile) // Uses only checker 1's state.
})

goroutine A: Lock locks[0] → check service.ts with checker 0 ───→ Unlock
goroutine B: Lock locks[1] → check app.ts with checker 1 ───────→ Unlock

The locks differ, so A and B can make progress at the same time.

This is work that waits. service.ts and api.ts are different files, but both are assigned to checker 0 and therefore both need locks[0].

// Explanatory pseudocode: both jobs need the same checker 0.
go withExclusiveChecker(locks[0], func() {
    typeCheck(checkers[0], serviceFile)
})

go withExclusiveChecker(locks[0], func() {
    typeCheck(checkers[0], apiFile) // Cannot progress until the earlier work unlocks checker 0.
})

goroutine A: Lock locks[0] → check service.ts with checker 0 ───→ Unlock
goroutine B: tries Lock locks[0] → waits ───────────────────────→ check api.ts → Unlock

B waits so that both jobs never touch one checker's state at once.

If two goroutines tried to check the same service.ts file, the second would also wait on locks[0]. However, the central purpose is not to protect one file; it is to prevent multiple jobs that share one checker from corrupting its caches and state at the same time.

The earlier examples simplified mutex use by passing a lock directly. The real getCheckerForFileExclusive instead receives a file and finds the required mutex itself. It has four steps:

Look up the file’s assigned checker with fileAssociations[file].
Find that checker’s position in checkers.
Lock the mutex at the same position, locks[idx].
Return the checker and a release function for the caller to invoke when its work is done.

The following excerpt implements exactly that correspondence.

// Excerpt: the pool selects the file's checker, then protects that checker.
func (p *checkerPool) getCheckerForFileExclusive(ctx context.Context, file *ast.SourceFile) (*checker.Checker, func()) {
    p.createCheckers()

    c := p.fileAssociations[file] // The association is created once for this program.
    idx := slices.Index(p.checkers, c)
    p.locks[idx].Lock() // Do not let two callers mutate or read this checker unsafely.

    return c, sync.OnceFunc(func() {
        p.locks[idx].Unlock() // The caller releases the checker when its operation ends.
    })
}

c is the checker from step 1, and idx is the checker’s position found in step 2. p.locks[idx] is the mutex from step 3. The second returned value is the release function, which the caller uses when it is done with the checker. sync.OnceFunc is a Go helper that makes the inner Unlock() run only once, even if the release function is accidentally called twice.

The reused unit here is a real checker with caches and mutable semantic state, not merely an execution slot. The source comment describes each partition as a checker with its own symbol, type, and instantiation caches. Multiple checkers may work at the same time, but one checker is never treated as a thread-safe shared bag of type state.

Why file assignment is a graph-partitioning problem

The implementation models the program’s in-project resolved imports as an undirected graph.

source file  = a vertex
resolved import between in-project files = an edge
checker      = a partition of vertices

An import is directional in source code: app.ts imports service.ts. For cache locality, however, the relationship is useful in both directions. If two files share a checker, either one may benefit from type information that the other caused that checker to construct. The implementation therefore uses an undirected adjacency graph for this decision.

The source comments describe the objective in a compact form:

affinity(partition) - alpha × incrementalLoadPenalty(partition)

“Affinity” means that a file gets a better score for joining a checker that already owns adjacent imported files. “Load penalty” means that a checker becomes less attractive as its estimated workload grows. Neither term should win unconditionally: putting every connected file together harms parallelism; spreading every file evenly can duplicate semantic cache construction.

The production code uses a weighted adaptation of the FENNEL streaming graph-partitioning objective. You do not need to know FENNEL to understand the practical rule: score every checker by nearby import relationships, subtract a penalty for additional assigned work, and choose the best stable result.

Here is a deliberately simplified version of that decision. It is explanatory code, not a copy of the TypeScript implementation.

// chooseChecker assigns one file to the most suitable checker.
func chooseChecker(file int, neighbors [][]int, assignment []int, loads []int, weight int) int {
    bestChecker := 0
    bestScore := math.Inf(-1)

    for checker := range loads {
        sharedNeighbors := 0
        for _, adjacentFile := range neighbors[file] {
            if assignment[adjacentFile] == checker {
                sharedNeighbors++ // Related files on one checker can reuse its semantic caches.
            }
        }

        nextLoad := loads[checker] + weight
        loadPenalty := float64(nextLoad) // The real compiler uses a calibrated convex penalty.
        score := float64(sharedNeighbors) - loadPenalty

        if score > bestScore {
            bestChecker, bestScore = checker, score
        }
    }

    return bestChecker
}

The real function is more careful. It estimates each file’s weight from syntax-node count, source-text length, and import count; it establishes a preferred maximum load; and it uses deterministic tie-breaking. Those details prevent a highly connected or expensive file from causing one checker to become the bottleneck.

Determinism is part of the design, not a by-product

Parallel systems often become non-deterministic by accident. If a scheduler assigns the next completed task to the next available worker, two runs can choose different work sequences. That is acceptable for many batch jobs, but it is a poor default for a compiler: developers expect the same input and configuration to produce the same diagnostics and output.

TypeScript 7 therefore computes associations before it begins file-oriented type-checking. The association code has explicit stable rules: it can preserve program order, or sort source files before declaration files and use their estimated weight; ties fall back to stable file indexes. Once constructed, fileAssociations maps every source file to its selected checker.

The subsequent diagnostics collection preserves the source-file index as well. The following excerpt shows the essential idea.

// Excerpt, shortened: each file's diagnostics go to its own stable slot.
func (p *Program) collectCheckerDiagnosticsFromFiles(ctx context.Context, sourceFiles []*ast.SourceFile, collect func(context.Context, *checker.Checker, *ast.SourceFile) []*ast.Diagnostic) [][]*ast.Diagnostic {
    diagnostics := make([][]*ast.Diagnostic, len(sourceFiles))

    p.compilerCheckerPool.forEachCheckerGroupDo(ctx, sourceFiles, p.SingleThreaded(), func(c *checker.Checker, fileIndex int, file *ast.SourceFile) {
        diagnostics[fileIndex] = collect(ctx, c, file)
    })

    return diagnostics
}

Workers may complete at different times, but completion order does not determine where results are stored. Later processing can concatenate, sort, and deduplicate diagnostics. This is a broadly useful pattern whenever parallel work must retain a caller-visible order: assign stable input indexes before concurrency begins, store each result by index, and make ordering explicit at the merge boundary.

There is an important limit. The TypeScript 7 release notes say that changing the number of checkers can expose rare order-dependent results. A fixed --checkers value gives a stable partition for a stable input, but changing that value deliberately changes the partitioning configuration. Teams that need identical behavior across environments can therefore pin the checker count.

The worker count is a performance and memory dial

The pool defaults to four checkers. --checkers can choose another count, while --singleThreaded sets the count to one and also disables parsing and emitting parallelism. The implementation caps the count to the number of program files and to 256, so a configuration cannot create more checkers than there are files to assign.

// Excerpt: the default and the two configuration paths.
checkerCount := 4
if program.SingleThreaded() {
    checkerCount = 1
} else if c := program.Options().Checkers; c != nil {
    checkerCount = *c
}
checkerCount = max(min(checkerCount, len(program.files), 256), 1)

More checkers can reduce wall-clock time when a project has enough independent work and CPU capacity. They also increase the chance that separate checker caches recreate similar type information. The release notes make this trade-off explicit: increasing --checkers can speed up larger builds, but usually costs more memory. --checkers 1 removes inter-checker duplication at the cost of type-checking parallelism.

This is why “use every CPU core” is not automatically the right compiler setting. The appropriate value depends on project shape, available memory, CI runner capacity, and whether type-checking or another phase is actually the bottleneck. A monorepo has a second control, --builders, for project-reference builds; its concurrency combines multiplicatively with checker concurrency, so --checkers 4 --builders 4 may allow up to sixteen checkers at once.

What application developers can borrow from this design

Most applications do not need graph partitioning. The transferable lessons are smaller and more practical.

If a worker has expensive reusable state, treat locality as a first-class concern. A database connection with prepared statements, a compiler cache, a GPU context, or a model session may benefit from assigning related work consistently rather than sending every task to whichever worker happens to be idle.

If the work has a visible order, preserve that order separately from execution. Parallelism should change how long a job takes, not randomly change the sequence of diagnostics, records, or user-facing messages.

Finally, expose concurrency as a control rather than an opaque promise. TypeScript 7 gives users a default, a way to tune it for larger machines, and a fully single-threaded mode for constrained environments or debugging. That makes the performance trade-off observable and reversible.

Closing thought

TypeScript 7’s speedup is not only a consequence of moving from JavaScript to Go. The native implementation also makes it practical to use shared-memory parallelism, and the checker pool shows the care required to use that parallelism well.

The key idea is not “run type checking on four workers.” It is “partition a program so that related work can reuse state, unbalanced work does not dominate the build, and the same configuration produces the same observable result.” That is a useful design lens for compilers, build systems, and any service that needs both concurrency and trustworthy output.

Related project

I develop Kinmokusei, a programming language with TypeScript-inspired syntax that compiles to readable Go. The project is relevant here because it works with the normal Go toolchain and ecosystem while exploring a different source-language design.

Inside TypeScript 7: Arena Allocation and AST Memory Layout

puffball1567 — Sun, 20 Sep 2026 07:11:52 +0000

When a compiler reads source code, it first turns the text into a tree called an AST (abstract syntax tree). Each part of the source—a function call, identifier, or expression—becomes a small object called a node in that tree. A large project can therefore create millions of nodes. TypeScript 7's Go compiler uses a small reusable allocator, called a typed arena, for selected node types such as CallExpression. This article follows the path from creating a call-expression node to returning the common *Node value, then separates what this allocator guarantees from what it does not.

The intended reader works with Go or TypeScript but does not need compiler-internals experience. The topic is a practical memory-layout question: what a typed arena changes about AST allocation, and what it does not.

What problem is this arena solving?

A compiler creates many nodes while it reads and analyzes source files. Here, an allocation means asking Go to reserve memory for one new object. If every node is created separately, Go's memory manager must handle many individual allocations, and objects of the same kind can be placed far apart in memory. TypeScript 7 gives some specific node structs—such as CallExpression—their own arenas. This appears intended to create repeated nodes in small batches instead.

Why care about individual heap allocations?

Go can allocate objects efficiently, but each allocation still requires work. Objects that must outlive the current function are typically placed in the heap, the area of memory that Go's garbage collector manages. Creating many separate heap objects increases allocator work and gives the garbage collector more objects to keep track of. An arena does not remove the pointers stored inside an AST node, so it does not eliminate all garbage-collection work. Instead, it can replace many small allocations with a smaller number of slice allocations, where one slice holds many values of the same node type.

The difference is easiest to see as a shape of allocations, not as a special kind of memory.

Direct allocation: one runtime-managed object per node

&CallExpression{} ──► [CallExpression]
&CallExpression{} ──► [CallExpression]
&CallExpression{} ──► [CallExpression]
                         ...
runtime sees many separately allocated objects

Typed arena: one backing slice holds several values of the same type

NodeFactory
  └─ callExpressionArena ──► [CallExpression | CallExpression | CallExpression | ...]
                                  ^ each New() returns a pointer to one element
runtime sees a much smaller number of backing-slice allocations

This allocation pattern may also fit an AST's lifetime. A parsed tree is commonly kept as a whole while later compiler stages use it; a compiler usually does not discard one call-expression node at a time. Keeping same-type values in batches can therefore be a reasonable trade-off. In one batch, values sit next to one another in the slice's underlying array. When that batch fills, the arena creates a new array instead of moving the old one, so pointers already returned to callers remain valid.

The repository does not state a universal rationale for every arena choice, so these are the properties and typical benefits of the pattern—not a claim about an unstated TypeScript 7 performance result. It also does not mean that the whole AST becomes one contiguous block or that every tree walk becomes fast. The rest of this article shows the narrower mechanism for CallExpression.

This is a companion to Inside TypeScript 7: How Its AST Nodes Are Built and Traversed. The two articles can also be read independently.

Source and license note

This article discusses the publicly available microsoft/TypeScript repository. TypeScript 7's Go compiler is under tsc/ and is licensed under the Apache License 2.0. Code blocks marked as excerpts are short portions of the upstream source; diagrams and explanatory text are original. File-and-line citations in this article are pinned to source snapshot f29aeb9 so that later changes to main do not move the cited code.

Source excerpts are from Microsoft’s TypeScript project:
https://github.com/microsoft/TypeScript

Licensed under the Apache License, Version 2.0.
A copy of the License is available at:
https://github.com/microsoft/TypeScript/blob/main/LICENSE.txt

First, what an arena allocator usually means

An arena allocator is a way to manage the lifetime of a group of objects together. Instead of requesting memory separately for every object and releasing each one separately, a program creates an arena, asks it for objects as needed, and later discards or resets the entire arena at once. This is useful when a group of objects is expected to become unnecessary at roughly the same time—for example, temporary data used while processing one request or one compiler phase.

Typical arena lifetime

create arena
    │
    ├─ allocate object A
    ├─ allocate object B
    └─ allocate object C
    │
all three objects become unnecessary together
    │
reset or discard the arena
    └─ release the group as one unit

The important idea is not that all memory is reserved up front. An arena can obtain more memory in batches as it fills. What makes it an arena is that allocation is grouped and its lifetime is commonly controlled at the arena level rather than one object at a time.

How TypeScript 7's `Arena` differs from a classic arena

TypeScript 7 uses the name Arena, but its implementation is deliberately smaller and works within ordinary Go memory management. It is an ordinary library data structure, not a special feature of the Go runtime. It stores a growable list (a slice) of one node type and returns pointers to entries in that list. It has New() and slice-allocation methods, but no public Free() or Reset() method that immediately releases all entries.

Classic arena                                 TypeScript 7 core.Arena[T]

program controls reset / discard              no explicit Free or Reset API
objects can be released as one region         Go's GC reclaims memory when nothing references it
often owns a general-purpose byte region      owns typed slices such as []CallExpression

That distinction matters. A NodeFactory owns an Arena[CallExpression], but Go does not free its memory merely because one call-expression node is no longer needed. The backing arrays become collectible only after the factory, the AST nodes, and any other references keeping those arrays alive are no longer reachable. This design groups allocation, but it does not introduce manual memory management or bypass Go's garbage collector.

The relevant TypeScript 7 implementation is short. Source: tsc/internal/core/arena.go, lines 7–21.

// Annotated excerpt: internal/core/arena.go
type Arena[T any] struct {
    data []T // One backing slice for entries of the same concrete type.
}

func (a *Arena[T]) New() *T {
    if len(a.data) == cap(a.data) {
        nextSize := nextArenaSize(len(a.data)) // Decide the capacity of the next batch.
        a.data = slices.Grow[[]T](nil, nextSize) // Start a new backing slice; old pointers stay valid.
    }
    index := len(a.data) // The next unused element becomes the new entry.
    a.data = a.data[:index+1] // Extend the slice length so that entry belongs to the arena.
    return &a.data[index] // Return a pointer to that concrete value.
}

Arena[CallExpression] therefore means “an arena whose list contains CallExpression values.” Its New() method returns a pointer, *CallExpression, to one newly reserved entry. The standard-library documentation for slices.Grow explains the capacity-growth operation used here.

TypeScript 7 keeps an arena per selected node type

NodeFactory is the object responsible for constructing AST nodes. Think of it as the place that both knows how to fill in a node's fields and owns the typed storage used while making that kind of node. For example, after the parser recognizes client?.request<User>(id), it can ask the factory to make one call-expression node from the pieces it already recognized.

parser has recognized: client?.request<User>(id)
        │
        │ passes the four meaningful pieces to NodeFactory
        ▼
NewCallExpression(expression, ?., <User>, (id))
        │
        ├─ reserve an empty CallExpression entry from its arena
        ├─ put those four pieces into that entry
        └─ return the entry's shared *Node portion

NodeFactory has many fields. The two fields relevant to this article are its typed arena and its hooks field. hooks is simply a group of optional functions that a caller can provide while creating a factory; the next section shows exactly when OnCreate is called. Sources: tsc/internal/ast/ast.go, lines 61–65 for the hooks and tsc/internal/ast/ast_generated.go, lines 20–25 for the typed arena field.

// Annotated excerpts, shortened to the fields relevant here.
type NodeFactoryHooks struct {
    OnCreate func(node *Node)                 // Optional function called after creating a node.
    OnUpdate func(node *Node, original *Node) // Optional function called after updating a node.
    OnClone  func(node *Node, original *Node) // Optional function called after cloning a node.
}

type NodeFactory struct {
    hooks                NodeFactoryHooks          // The optional functions supplied when this factory was created.
    callExpressionArena core.Arena[CallExpression] // Storage used when constructing CallExpression values.
}

The full CallExpression object stores information that only a call expression needs: what is being called, whether ?. is present, and its type and ordinary arguments. It also contains a shared Node portion used by every kind of AST node. The generated type and factory then look like this. Source: tsc/internal/ast/ast_generated.go, lines 4256–4274.

// Annotated excerpt: internal/ast/ast_generated.go
type CallExpression struct {
    LeftHandSideExpressionBase // Embeds common behavior for an expression that can appear on the left-hand side.
    DeclarationBase            // Embeds declaration-related shared state.
    CompositeBase              // Reaches the shared Node header through the embedded base types.
    Expression       *Expression        // The expression being called, such as client.request.
    QuestionDotToken *QuestionDotToken  // The ?. token, when this is an optional call.
    TypeArguments    *TypeList          // Type arguments such as <User>, when present.
    Arguments        *ElementList       // Ordinary call arguments such as (id).
}

func (f *NodeFactory) NewCallExpression(expression *Expression, questionDotToken *QuestionDotToken, typeArguments *TypeList, arguments *ElementList, flags NodeFlags) *Node {
    data := f.callExpressionArena.New() // Reserve a *CallExpression entry in this factory's arena.
    data.Expression = expression         // Store the callee.
    data.QuestionDotToken = questionDotToken // Store ?. or nil.
    data.TypeArguments = typeArguments   // Store <T> arguments or nil.
    data.Arguments = arguments           // Store the ordinary argument list.
    node := f.newNode(KindCallExpression, data) // Initialize and return the embedded common Node.
    node.Flags |= flags & NodeFlagsOptionalChain // Preserve the optional-chain bit from the caller.
    return node // Callers use the common *Node API rather than *CallExpression directly.
}

For client?.request<User>(id), those fields represent the called expression, the optional-chain token, type arguments, and ordinary arguments. Read the code one line at a time:

f.callExpressionArena.New() returns the address of one empty CallExpression already stored in the arena. The local variable named data receives that address.
Lines such as data.Expression = expression write values into that one CallExpression.
f.newNode(KindCallExpression, data) receives the address of that same CallExpression. It initializes the shared Node portion contained inside the object.
The returned *Node is not a new, separate object. It is the address of the common Node portion inside the same CallExpression.

In short, the factory reserves one CallExpression in the arena, fills its call-specific and shared fields in order, then returns it in a form that later code can treat as a general AST node. The full generated implementation, lines 4256–4289 also shows its child-traversal method.

The allocation and initialization path is therefore as follows. There is one object throughout this flow—not one CallExpression object plus another Node object.

NewCallExpression(...)
        │
        ├─ callExpressionArena.New()
        │       └─ returns one *CallExpression inside a batch
        │
        ├─ write Expression / TypeArguments / Arguments into that value
        │
        └─ newNode(KindCallExpression, data)
                └─ initializes the shared Node portion inside that same object, then returns *Node

What `NodeFactory.newNode` does

There are two functions named newNode. The call in NewCallExpression is the method on NodeFactory, written f.newNode(...). Its job is deliberately small: count that the factory made one more node, then pass the work and the factory's hooks to the package-level newNode(...) function.

// Excerpt: tsc/internal/ast/ast.go, lines 75–88.
// nodeData and Node are defined in the next section.
func (f *NodeFactory) newNode(kind Kind, data nodeData) *Node {
    f.nodeCount++                 // Record that this factory created one more AST node.
    return newNode(kind, data, f.hooks) // Delegate the shared-field initialization below.
}

// This package-level helper is the second function with the same name.
func newNode(kind Kind, data nodeData, hooks NodeFactoryHooks) *Node {
    n := data.AsNode() // Find the common Node portion inside the full object.
    n.Loc = core.UndefinedTextRange() // Give its source range an initial value.
    n.Kind = kind // Record the supplied kind; here, it is KindCallExpression.
    n.data = data // Keep a way back to the full CallExpression object.
    if hooks.OnCreate != nil {
        hooks.OnCreate(n) // Run an optional callback after initialization.
    }
    return n // Return the common Node portion inside that same object.
}

When does `OnCreate` run?

OnCreate is not an event that fires automatically at some later time. It is an optional function value supplied when a factory is created. It runs synchronously during node creation only when both of these conditions are true:

The code that created this NodeFactory provided a non-nil OnCreate callback.
A factory method reaches the package-level newNode, which checks hooks.OnCreate != nil and calls it directly.

The printer is one concrete setup site:

// Shortened excerpts: tsc/internal/printer/factory.go, lines 18–24,
// and tsc/internal/printer/emitcontext.go, lines 71–73.
func NewNodeFactory(context *EmitContext) *NodeFactory {
    return &NodeFactory{
        NodeFactory: *ast.NewNodeFactory(ast.NodeFactoryHooks{
            OnCreate: context.onCreate, // Register this function on the AST factory.
            // OnUpdate and OnClone are also registered in the real code.
        }),
    }
}

func (c *EmitContext) onCreate(node *ast.Node) {
    node.Flags |= ast.NodeFlagsSynthesized // Mark a printer-created node as synthesized.
}

create factory with OnCreate callback
        │
        ▼
factory.NewCallExpression(...)
        │
        ▼
newNode(...)
        │
        ├─ OnCreate is nil  ───► do nothing
        └─ OnCreate is set  ───► call it immediately with the new *Node

For example, the printer creates its factory with context.onCreate as the callback. That callback marks each node created through this printer factory as synthesized. A factory created with ast.NodeFactoryHooks{} instead has no callback, so this step is skipped. Sources: tsc/internal/printer/factory.go, lines 18–24, tsc/internal/printer/emitcontext.go, lines 71–73, and tsc/internal/ast/ast.go, lines 75–83.

So the two names represent two levels of responsibility:

f.newNode(...)                  newNode(...)
NodeFactory method              package-level helper

increments this factory's       fills the common Node fields
node count                      and runs an optional creation hook
        │                                  │
        └────────────── calls ────────────┘

The factory links the common node header back to the concrete object

Every AST node needs some information that is common to all nodes: its kind, flags, source range, and parent. TypeScript 7 puts this shared information in Node, which works as a small common header inside the full object. The private nodeData interface describes what a full node object must provide. The package-level newNode shown above uses its AsNode method to find that embedded common header. Sources: tsc/internal/ast/ast.go, lines 75–88, lines 180–187, and lines 1184–1205.

// Annotated excerpt, with nodeData shortened to the method used below.
type Node struct {
    Kind   Kind            // Identifies which concrete AST node this is.
    Flags  NodeFlags       // Holds shared syntactic and analysis flags.
    Loc    core.TextRange  // Records the node's source range.
    Parent *Node           // Points to the enclosing node when a parent has been assigned.
    data   nodeData        // Points back to the full concrete object, such as *CallExpression.
}

type nodeData interface {
    AsNode() *Node // Returns the common Node embedded in the concrete object.
    // The real interface also defines traversal, cloning, and analysis methods.
}

CallExpression reaches Node through its embedded base types. In other words, the full call-expression object contains the shared Node portion inside it. newNode obtains that inner Node as n, then stores a reference to the full *CallExpression back in n.data.

*CallExpression allocated by callExpressionArena
├─ embedded base types
│  └─ shared Node  ← returned *Node
│     └─ data ────────────────┐
├─ Expression                 │
├─ TypeArguments              │
└─ Arguments                  │
                              │
data holds *CallExpression ───┘

This is why later code can start from a generic *Node, inspect Kind, and recover its concrete representation when necessary. The cited lines above show the production definitions, including the full nodeData interface.

What this memory layout guarantees

Within one active arena slice, entries of the same type are adjacent array elements. If a factory creates several CallExpression values while the slice still has capacity, their CallExpression structs are stored together. That can improve locality when code repeatedly works on the same node type.

When the slice is full, this arena does not grow the old backing array in place. It creates a new backing slice with slices.Grow(nil, nextSize) and begins placing subsequent values there. Existing pointers still point to elements in the old backing array; the allocator never moves or overwrites those entries. As long as the AST retains those pointers, Go retains the old allocation too.

The result is better described as type-local batches than as “one contiguous AST.”

CallExpression arena
├─ batch A: CallExpression, CallExpression, CallExpression, ...
└─ batch B: CallExpression, CallExpression, ...

Identifier arena
└─ its own batches of Identifier values

Other node types
└─ their own allocation strategies and locations

The pointers inside a call expression can lead to identifiers, argument lists, tokens, or other node types stored elsewhere. Tree order, source order, and physical memory order are therefore different concepts.

Why not put every node type in one arena?

The repository does not state one universal policy for which node types receive an arena. The generated factory includes arenas for many types, while some constructors allocate with a direct &Type{} expression. It would be speculation to treat the presence of an arena as proof that one node type is always more important than another.

What can be stated from the code is narrower: the design permits the factory to choose an allocation strategy per concrete type while preserving the same returned *Node API. Callers of NewCallExpression do not need to know whether the concrete object came from an arena or a direct allocation.

The trade-off: locality and allocation patterns, not automatic speed

An arena can reduce per-object allocation work and group same-type objects, but it adds a custom lifetime and growth model. It also does not make arbitrary AST traversals cache-friendly: a traversal frequently follows pointers between different types and different batches.

TypeScript 7's overall performance comes from more than this allocator. The TypeScript team attributes TypeScript 7's gains to native code, shared-memory parallelism, and other optimizations; an AST arena alone does not explain the result. The TypeScript 7 announcement provides the broader performance context.

Reference measurement: does the expected allocation effect appear?

The mechanism above suggests that replacing one allocation per node with type-local batches should greatly reduce the number of objects allocated and tracked by the runtime. I tested that expectation with a small Go benchmark that constructs one live 100,000-node binary tree. The direct version allocates each node with &node{}; the arena version matches TypeScript 7's slice-backed growth policy, doubling a batch up to 256 elements and then allocating additional 256-element batches. This is an explanatory microbenchmark, not a TypeScript compiler benchmark: it does not parse TypeScript, type-check, emit output, or measure the production node types.

On Go 1.23.5, Linux/amd64, and one CPU on an AMD Ryzen 5 5600H, five runs produced the following medians. The final column comes from a separate forced-GC measurement after constructing one retained tree; it is not a testing.B allocation result.

Construction strategy	Median time for 100,000 nodes	Bytes/op	Allocations/op	Retained heap objects after one live tree
Direct `&node{}` allocation	13.59 ms	7,202,816	100,001	99,994
Typed growing arena	9.50 ms	6,422,288	350	355

In this deliberately narrow setup, the expected effect appeared: batching reduced allocation operations by about 99.7% and construction time by about 30%. Retained bytes were also lower here, but that is not guaranteed. An arena keeps its backing batches alive, including unused capacity in the final batch. This result supports the expected benefit of reducing individually allocated and tracked objects; it does not prove that an arena is always faster or smaller for every AST workload.

The reusable lesson is to measure the allocation and traversal pattern first. A typed arena is useful when a program creates many short- or similarly-lived objects of known concrete types. It is not a default replacement for ordinary Go allocation.

Kinmokusei

Kinmokusei is a programming language with TypeScript-inspired syntax that compiles to readable Go. It is designed to work with the normal Go toolchain and package ecosystem.

Jev vs LLMs: When Software Needs a Decision Instead of Generated Text

puffball1567 — Fri, 18 Sep 2026 06:36:22 +0000

Many developers first meet Jev and ask a reasonable question: “Is this just a smaller LLM that returns JSON?” The useful answer is no—but it also is not a replacement for an LLM. Jev is designed for a narrower job: evaluate a piece of application state against questions that the program defines, then return typed decisions with probabilities and confidence. An LLM is designed to generate language. Once that difference is clear, the practical boundary becomes much easier to see.

This article explains the model in plain terms, compares its strengths and limits with text-generating LLMs, and shows where a combined design is more useful than choosing one model for everything. Jev was announced by TypeSafe AI on September 15, 2026 and is currently an early-access product, so providers, API details, prices, and performance claims should be checked again before production adoption.

Sources and scope

Product behavior and the API-shaped example below are based on TypeSafe AI's Jev introduction and Cloudflare's Jev model documentation. Performance and price figures attributed to TypeSafe are vendor claims, not independent benchmarks. The diagrams, explanations, and application code in this article are original.

Jev in one sentence: state in, defined decisions out

An LLM is usually asked to write the next piece of text. For example: “Read this support ticket, explain the problem, and draft a reply.” The response can be useful, but it is open-ended text. Software must still decide how to parse it, validate it, and react if the model produces an unexpected answer.

Jev starts from a different contract. The application sends state plus a fixed set of questions. Each question specifies the allowed answer shape: a binary judgment, a choice from named options, or a score against a defined scale. Jev returns one value for each question, along with probabilities or confidence where the response type supports them.

Support ticket + account data + policy
                 │
                 ▼
     Application-defined questions
     ├─ Is the request urgent?          → binary probability
     ├─ Which team owns it?              → one named choice
     └─ How risky is the situation?     → score on a fixed scale
                 │
                 ▼
       Typed answers + confidence
                 │
                 ▼
  Code applies a threshold, routes, or asks a person to review

The model is not deciding what an application can do. The developer still defines the actions, allowed categories, rules, and escalation path. Jev supplies a probabilistic judgment inside that bounded space.

Why this is not merely “LLM JSON mode”

An LLM can be constrained to produce JSON or call a tool with a schema. That is often a good design. Some provider modes can enforce schema conformance, but the LLM still generates an output token sequence and the application must decide whether a schema-valid result is semantically suitable and safe for the next action.

TypeSafe positions Jev as a System One model: a model trained and served for parallel, typed decisions rather than sequential text generation. Its public interface defines the possible answers in advance and returns calibrated probabilities and confidence. In that sense, JSON is not the product's primary abstraction; a decision schema is.

This is an interface and workflow distinction, not a guarantee that one model is always more intelligent. A valid choice can still be the wrong choice. “No hallucinated text” means Jev cannot invent a free-form explanation or an undeclared category; it does not mean it cannot misclassify an ambiguous ticket, misunderstand a policy, or receive incomplete state.

Jev vs LLM: the practical comparison

Question	Jev	Text-generating LLM
Primary output	A declared binary judgment, choice, or score	Newly generated text or code
Best input shape	Application state plus a bounded decision schema	Natural-language requests, documents, conversation, and broad context
Can it write an email, explanation, or program?	No	Yes
Can it select a known route or apply a rubric?	Yes; this is its intended role	Yes, but the integration must still decide whether a valid result is suitable for the next action
Can it invent a category outside the schema?	No	It can, unless the integration constrains and validates output
Uncertainty signal	Returns probabilities and confidence for supported decision types; TypeSafe describes these as calibrated	A provider may expose scores or an application may ask for an estimate, but there is no uniform decision-specific calibration contract
Good latency/cost target	High-volume, bounded decisions inside a program	Rich interaction, generation, synthesis, and open-ended reasoning
Key limitation	Cannot generate novel text, plans, categories, or explanations	Output is flexible, so software must defend against invalid or unsuitable results

The table describes intended use, not a universal quality ranking. A simple deterministic rule should remain ordinary code; neither Jev nor an LLM should be asked whether amount > 1000 when the application can calculate it exactly.

A concrete example: triage, not customer support by itself

Consider an incoming support ticket. A conventional LLM prompt may ask for both a classification and a response. That is convenient for a human operator, but it mixes two jobs: deciding how to route work and writing language for the customer.

With Jev, the routing decision can be expressed separately. This adapted Cloudflare Workers example follows the documented state and questions request shape.

const response = await env.AI.run("typesafe/jev", {
  // State is the evidence Jev may use for every question in this request.
  state: {
    ticket: {
      subject: "Charged twice",
      message: "I was charged twice for order A-104. Please refund the duplicate.",
    },
    // The application supplies relevant facts instead of asking the model to fetch them.
    order: {
      charges: [
        { amountUsd: 49, status: "captured" },
        { amountUsd: 49, status: "captured" },
      ],
    },
    refundPolicy: "Duplicate charges are eligible for a refund.",
  },
  questions: {
    department: {
      type: "choice",
      instructions: "Which team should handle this ticket?",
      // Jev must select one declared key; it cannot make up a fifth team.
      criteria: {
        billing: "Charges, invoices, refunds, or subscriptions",
        technical: "Product bugs, outages, or integrations",
        account: "Login, password, profile, or security issues",
        other: "Does not fit the listed teams",
      },
    },
    needsHumanReview: {
      type: "noul",
      // `noul` is Jev's documented binary-probability question type.
      instructions: "Should a person review this request before any refund action?",
    },
  },
});

// The exact response types depend on the provider SDK. The documented response
// contains a selected choice and confidence/probabilities for a choice question.
const department = response.answers.department;
if (department.choice === "billing" && department.confidence >= 0.9) {
  await enqueueForBillingReview(); // Route work; do not issue a refund automatically here.
} else {
  await enqueueForHumanTriage(); // Low confidence or another route gets a safer path.
}

The model has not performed a refund, queried a payment provider, or created a policy. It has only supplied a bounded judgment. The application owns authorization, idempotency, audit records, and the final state change.

Where Jev is strong

Jev is a natural fit when an application already knows the set of possible actions but needs help deciding which one fits unstructured evidence.

Use case	Decision schema	What the application still owns
Support routing	Department, urgency, escalation	Queue selection, staffing, access control
Content or log triage	Relevance, severity, category	Retention, alerting, investigation
Policy review	Eligible / not eligible / uncertain	The policy source, final approval, audit trail
Quality gates	Pass / revise / reject against a rubric	The rubric, release process, exceptions
Agent routing	Use tool A, tool B, or request review	Tool permissions, budgets, side-effect handling

These cases share an important property: the output space can be defined before the request arrives. That lets a program associate each answer with an explicit branch and reserve uncertain cases for review.

Where an LLM remains the right tool

Use an LLM when the valuable output is language or when the possible answer is not known in advance. Examples include explaining an incident, summarizing a long investigation, writing a migration plan, drafting a customer response, producing code, or exploring an unfamiliar document set.

An LLM is also useful before Jev in a workflow. It can turn a large, messy body of information into a proposed structured state, suggest candidate categories, or write a human-readable explanation. Those outputs should still be validated before becoming inputs to an automated decision.

Unstructured documents ──► LLM extracts or summarizes ──► validated state
                                                              │
                                                              ▼
                                                    Jev selects a route
                                                              │
                                                              ▼
                                                   code acts or escalates
                                                              │
                                                              ▼
                                      LLM explains the result to a person, if needed

This is often a better mental model than “Jev versus LLM.” An LLM handles open-ended language work; Jev supplies repeated bounded judgments; ordinary code enforces deterministic rules and carries out side effects.

Strengths do not remove operational risk

Typed output removes one integration failure mode: malformed output or an undeclared answer. It does not establish that the input state is complete, that a policy is current, or that a high-confidence decision is safe to execute without review.

Before automating a consequential action, define a conservative threshold, record the state and decision used, make the action idempotent, and give humans an escalation path. For a payment, suspension, deletion, medical, legal, or security action, a typed model result should normally be one signal in a controlled workflow—not the only authorization check.

The boundary to remember

Choose Jev when the question is: “Given this state and these allowed outcomes, which branch should software take?” Choose an LLM when the question is: “What should we say, create, explain, or explore?” Use plain code when the answer follows from deterministic data and rules.

That boundary is why Jev is interesting. It does not try to make chatbots obsolete. It makes a different part of AI integration—frequent, structured, uncertainty-aware decisions—into a first-class model interface.

Inside TypeScript 7's Go Port: Designing Typed AST Nodes Without a Giant Struct

puffball1567 — Thu, 17 Sep 2026 17:34:52 +0000

TypeScript 7 is a version of TypeScript whose compiler and editor tools were reimplemented in Go. This article examines one part of that implementation: its AST node model.

The intended reader works with Go or TypeScript but does not need compiler-internals experience. The topic is a general modeling problem: how to represent several related data shapes without putting every possible field into one oversized struct full of optional fields.

Source and license note

This article discusses the publicly available microsoft/typescript-go source repository, which is licensed under the Apache License 2.0. The implementation section includes short source excerpts; the remaining Go and TypeScript snippets are small, independently written examples. Links to the relevant upstream files are included where implementation details are discussed.

Source excerpts are from Microsoft’s TypeScript-go project:
https://github.com/microsoft/typescript-go

Licensed under the Apache License, Version 2.0.
A copy of the License is available at:
https://github.com/microsoft/typescript-go/blob/main/LICENSE

Step 0: compiler, transpiler, parser, and type checker

A compiler pipeline normally starts with a parser, which turns source text into an abstract syntax tree (AST). A type checker uses that tree to analyze types, and an emitter writes JavaScript or another output format. A compiler that emits another programming language is often called a transpiler; TypeScript-to-JavaScript is one example. This article focuses only on the AST as a data model, not on parsing or type-checking algorithms.

Step 1: a parser needs more than the original text

Suppose a compiler receives this code:

total(1, 2)

The parser represents this expression as an AST: a tree of nodes that capture source structure.

Call
├── Identifier: total
├── Number: 1
└── Number: 2

Here, Call, Identifier, and Number are node kinds: labels for distinct syntax roles. Later stages read this tree instead of re-interpreting source text.

Each kind needs different information.

An identifier needs text, such as total.
A number needs its value or original text.
A call needs the expression being called and its arguments.

Some information is useful for every kind. For example, the compiler often needs the location of a node in the original file so it can show an error in the right place. It may also need a link to the node's parent.

This gives us the real design problem: how should one Go type represent what every node has, while still keeping call-only fields away from identifier-only fields?

Step 2: the simple approach is one large struct

A normal first implementation in Go is one struct. For a TypeScript reader, it is similar to defining one object shape with several optional properties.

type Node struct {
    Kind      Kind      // Says whether this is a call, identifier, or number.
    Start     int       // Byte position where this node begins in the source text.
    End       int       // Byte position immediately after the node ends.
    Parent    *Node     // The containing node, if there is one.
    Text      string    // Used by an identifier or number; unused by a call.
    Callee    *Node     // Used by a call; unused by an identifier or number.
    Arguments []*Node   // Used by a call; unused by an identifier or number.
}

This is not wrong. It is easy to create, easy to read, and often perfect for a small format.

The difficulty appears when the model grows. With this type, Go allows combinations that have no meaning. For example, an identifier can have both Text and Arguments, even though only a call should have arguments. The struct cannot express the rule itself; every part of the program must remember it.

if node.Kind == IdentifierKind {
    // `Text` is meaningful only after checking the kind.
    fmt.Println(node.Text)
}

One check is harmless. A compiler has many node kinds and many places that read them. Repeating the same checks makes it easier for one reader to forget a rule. Adding a new kind also tends to add more fields that are empty for nearly every existing node.

Step 3: TypeScript can describe valid shapes with a union

TypeScript has a discriminated union for this case. A shared tag, usually kind, connects a runtime value with the fields allowed for that shape. For a Go reader, it is a compile-time relationship between a tag value and the fields valid with it.

type IdentifierNode = {
  kind: "identifier"; // This fixed value identifies an identifier node.
  start: number; // Source position shared by every node.
  end: number;
  text: string; // Only an identifier has a name.
};

type CallNode = {
  kind: "call"; // This fixed value identifies a call node.
  start: number;
  end: number;
  callee: Node; // The expression to invoke.
  arguments: Node[]; // The values passed to that expression.
};

// A Node is one valid shape or the other, not an arbitrary mixture of both.
type Node = IdentifierNode | CallNode;

After checking kind, TypeScript narrows the union: it knows which fields are safe to use in that branch. This is checked when TypeScript is compiled, before the JavaScript runs.

function describe(node: Node): string {
  if (node.kind === "identifier") {
    // In this branch, TypeScript knows that `text` exists.
    return node.text;
  }

  // The only remaining shape is CallNode, so `arguments` exists here.
  return `call with ${node.arguments.length} arguments`;
}

The important benefit is not the syntax. It is that the type model says which combinations are valid.

Step 4: Go needs a different way to express the same separation

Go does not have built-in discriminated unions. TypeScript-go combines a shared struct header with a private interface. A Go interface can hold a concrete value that provides its methods, and a type assertion checks which concrete value it currently holds.

The TypeScript-go project uses those features to split its AST in two parts. The small example below is deliberately simpler than the real layout: its callData is not a TypeScript-go type.

A central Node holds data shared by all nodes.
A private nodeData value holds data that belongs to one specific node kind.

In the actual source, the shared Node has a kind, flags, a source range, an internal ID, a parent pointer, and private nodeData. The concrete nodeData values hold details such as identifier text, call arguments, and function bodies.

Here is a smaller example of the same idea. It is written for explanation, not copied from TypeScript-go.

type Node struct {
    Kind   Kind     // Shared: tells generic code which syntax form this is.
    Start  int      // Shared: start position in the input.
    End    int      // Shared: end position in the input.
    Parent *Node    // Shared: link to the containing node.
    // data is not a child node itself. It stores fields specific to this kind.
    // For a call expression, its concrete data can conceptually contain:
    //   Callee    *Node   // the expression being called
    //   Arguments []*Node // the expressions passed to the call
    data nodeData
}

// Visitor is the callback used while walking direct children.
// Returning true asks the traversal to stop early.
type Visitor func(*Node) bool

type nodeData interface {
    // Every kind-specific data type exposes its direct children.
    ForEachChild(Visitor) bool
}

type identifierData struct {
    Text string // Specific: only identifiers have identifier text.
}

func (identifierData) ForEachChild(visitor Visitor) bool {
    return false // An identifier is a leaf, so there is nothing to visit.
}

type callData struct {
    Callee    *Node   // Specific: the expression to call.
    Arguments []*Node // Specific: values supplied to the call.
}

func visit(visitor Visitor, node *Node) bool {
    if node != nil {
        return visitor(node) // Call the visitor only for a real child node.
    }
    return false // A missing optional child cannot stop the traversal.
}

func visitNodes(visitor Visitor, nodes []*Node) bool {
    for _, node := range nodes {
        if visitor(node) {
            return true // Stop as soon as the visitor asks to stop.
        }
    }
    return false
}

func (d callData) ForEachChild(visitor Visitor) bool {
    if visit(visitor, d.Callee) {
        return true // Do not inspect arguments after an early-stop request.
    }
    return visitNodes(visitor, d.Arguments) // Visit arguments in source order.
}

The real code starts from a concrete node object. CallExpression contains its child fields, and its factory obtains one from an arena before filling those fields. newNode obtains the embedded shared Node with data.AsNode(), sets its kind, and stores the same concrete object back in n.data. Therefore, for a call expression, n.data holds *CallExpression, not a separate callData value. See the actual CallExpression factory and the shared newNode function.

The traversal contract in the example is still useful, but the actual top-level dispatch has one important difference. Node.ForEachChild uses a generated switch on Kind, then type-asserts n.data and calls the concrete method:

func (n *Node) ForEachChild(v Visitor) bool {
    switch n.Kind {
    // ... other node kinds ...
    case KindCallExpression:
        return n.data.(*CallExpression).ForEachChild(v)
    }
    return false
}

CallExpression.ForEachChild then passes its direct Expression, optional QuestionDotToken, optional type arguments, and arguments to the visitor. In the upstream source, Visitor is func(*Node) bool; visit ignores a nil child and otherwise calls the supplied visitor; visitNodes applies that visitor to a list until it returns true. The true return is an early-stop signal, not an error. See the helpers and the concrete CallExpression traversal.

ForEachChild itself does not recursively walk the whole tree. It enumerates only direct children. The visitor supplied by its caller decides what to do with each child, including whether to recurse. A search visitor can use the early-stop result like this:

func Find(node *Node, matches func(*Node) bool) *Node {
    var found *Node
    var walk Visitor

    walk = func(current *Node) bool {
        if matches(current) {
            found = current
            return true // Tell every caller in the chain to stop.
        }
        return current.ForEachChild(walk) // Recurse only after testing this node.
    }

    if node != nil {
        walk(node) // Begin the depth-first traversal at the root.
    }
    return found
}

Here, walk is the actual visitor implementation. It checks the current node, recursively asks that node for its direct children, and returns true once it finds a match. Language-service features use the same separation: their visitor performs feature-specific work, while each AST node knows which fields are its children.

The word private matters here. In Go, a lower-case name such as data or nodeData cannot be used by code in another package. This serves the same purpose as keeping an implementation detail unexported from a TypeScript module.

Generic code can work with *Node and use the common fields. For example, a tree walker can report source locations for every node. When it needs to move down the tree, generated dispatch selects the concrete node and that node enumerates its children.

Step 5: the small example keeps `Kind` and data together

A constructor is a function that creates a value in a valid state. In Go, New... factory functions commonly play this role.

type Kind uint8

const (
    IdentifierKind Kind = iota // `iota` assigns the first numeric Kind value; it must use identifierData.
    CallKind                   // This kind must use callData.
)

The concrete data types used by the constructors are repeated here so their contents remain visible nearby.

type identifierData struct {
    Text string // The identifier's spelling, such as "total".
}

func (identifierData) ForEachChild(visitor Visitor) bool {
    return false // Identifiers are leaf nodes.
}

type callData struct {
    Callee    *Node   // The expression to call.
    Arguments []*Node // The expressions passed to the call.
}

func (d callData) ForEachChild(visitor Visitor) bool {
    if visit(visitor, d.Callee) {
        return true // Stop before visiting arguments when requested.
    }
    return visitNodes(visitor, d.Arguments)
}

func NewIdentifier(start, end int, text string) *Node {
    // Create an identifier kind with identifier-specific data.
    return &Node{
        Kind:  IdentifierKind,
        Start: start,
        End:   end,
        data:  identifierData{Text: text},
    }
}

func NewCall(start, end int, callee *Node, arguments []*Node) *Node {
    // Create a call kind with call-specific data.
    return &Node{
        Kind:  CallKind,
        Start: start,
        End:   end,
        data:  callData{Callee: callee, Arguments: arguments},
    }
}

The constructor is where the rule lives. Code elsewhere does not need to remember which fields a call requires. It calls NewCall, and that function pairs CallKind with callData.

When code needs information that belongs only to an identifier, it can use a method that checks the concrete data type.

func (n *Node) IdentifierText() (string, bool) {
    data, ok := n.data.(identifierData) // This succeeds only for an identifier.
    if !ok {
        return "", false // A call does not have identifier text.
    }
    return data.Text, true
}

n.data.(identifierData) is Go's type-assertion syntax. In the two-result form, data receives the concrete identifierData value only when the assertion succeeds, and ok reports whether it succeeded. When n.data holds callData, ok is false, so the function can safely return without reading Text. The Go language specification's type-assertion section documents both this safe two-result form and the one-result form that panics on a mismatch. Returning false here is safer than silently returning an empty string for the wrong kind of node.

What TypeScript-go adds beyond this small example

The real compiler needs more than a tiny expression tree. It needs to clone nodes, visit many different child arrangements, store information discovered during type checking, and handle a large number of language features.

TypeScript-go's private nodeData interface therefore has more methods than this example. The project also provides default base types, so an individual node implementation does not have to reimplement every method from scratch. The source comments explain that the team uses both interface methods and type switches: interface calls can help some paths, but hundreds of interface implementations also increase code size. The common Node definition and the private nodeData interface and default base type show those details.

The project is not offering nodeData as a public plugin API. It is an internal representation for a closed set of node kinds that the compiler itself owns. That is useful because the compiler can change traversal or cloning rules and update every known node type at once.

Does this AST design explain TypeScript 7's speed?

No. This design can make the model clearer and reduce opportunities to misuse fields, but it is not a general performance recipe.

The TypeScript team describes TypeScript 7's improvement as a combination of native code speed, shared-memory multithreading, and other optimizations. Parsing, type checking, and JavaScript output generation can run in parallel where that is safe. Type checking is more complicated because files share type information. TypeScript 7 uses a fixed number of type-checker workers so the work stays deterministic; using more workers can help large projects, but it can also use more memory. The official TypeScript 7 announcement explains that trade-off.

Reference measurement: traversal dispatch versus a flat struct

One reasonable question is whether the Kind switch and concrete type assertion in Node.ForEachChild make this representation slower than one large discriminated struct with every possible node field. The public repository does not provide a benchmark that answers that exact question, so I ran a small synthetic traversal benchmark as reference information. It is not a TypeScript-team result and should not be read as a performance claim about the complete compiler.

The benchmark constructed a 262,143-node binary AST, then walked every node with no parsing, allocation, binding, type checking, or emission inside the measured loop. The TypeScript-shaped variant used a common node header embedded in concrete node types and dispatched through a Kind switch followed by an assertion such as n.data.(*callNode). The comparison variant used one intentionally wider flatNode struct, retaining unused kind-specific fields at their zero values. Both variants visited the same tree shape and reported zero allocations during a traversal.

On Go 1.23.5, Linux/amd64, with one benchmark CPU on an AMD Ryzen 5 5600H, five runs produced these results:

Representation	Median full-tree traversal	Per-traversal allocations	Synthetic node size
Embedded header + `Kind` switch + concrete assertion	1.04 ms	0 B / 0 allocs	`callNode`: 48 B
One wider discriminated `flatNode`	1.16 ms	0 B / 0 allocs	`flatNode`: 104 B

In this intentionally narrow test, the switch-and-assert representation was about 11% faster at the median. A CPU profile also showed the dispatch method inlined by this Go version. This does not isolate the cost of a single assertion, and it does not establish that the same result applies to TypeScript 7's full set of node kinds or real-world projects. It does show that a flat struct is not automatically the faster traversal layout: larger per-node memory footprint and cache behavior are part of the trade-off too.

When is this pattern useful in an ordinary Go application?

Start with a normal struct when the data is small. A configuration value with two optional fields does not need an interface and several extra types.

This pattern becomes useful when all of the following are true:

Your program has a fixed set of data shapes with clearly different fields.
Many parts of the program need a small set of fields shared by every shape.
Invalid combinations of fields are causing repeated checks or bugs.
Central constructors and one traversal rule would make the model easier to understand.

The lesson is not “always use interfaces for trees.” It is simpler: keep shared data together, keep kind-specific data with its own kind, and make invalid combinations difficult to create.

Kinmokusei

Kinmokusei is a programming language with TypeScript-inspired syntax that compiles to readable Go. It is intended for writing web backends and Go libraries while using the normal Go toolchain and package ecosystem directly.

Go Concurrency Safety: Prevent Goroutine Leaks and Data Races

puffball1567 — Thu, 17 Sep 2026 00:31:11 +0000

Goroutines make it easy to begin concurrent work. Making that work stop reliably and share state safely takes a little more design. This follow-up explains two problems that often appear after a first worker-pool or channel implementation: a goroutine that never exits, and shared memory that two goroutines access at the same time.

If you have not read the first article, start with Go Concurrency: How to Run Parallel Tasks with Goroutines, Channels, and Context. It introduces goroutines, channels, sync.WaitGroup, bounded worker pools, and context.

What is a goroutine leak in Go?

A goroutine leak is a goroutine that is still alive even though the work it was created for is no longer useful. It is not necessarily a memory leak in the usual sense. The goroutine may be blocked while waiting to send to a channel, receive from a channel, acquire a lock, or complete an operation that nobody will ever observe.

One leaked goroutine may not be noticeable. A leak on every HTTP request, reconnect, failed job, or page refresh eventually consumes memory, file descriptors, connections, and scheduler time. The practical rule is simple: every goroutine needs a clear completion path and a clear cancellation path.

A common Go channel leak: the consumer stops early

In this example, the producer sends a sequence of values, but the consumer only wants the first one.

func numbers(out chan<- int) {
    defer close(out)

    for number := 1; number <= 3; number++ {
        out <- number // The producer waits until somebody receives.
    }
}

func firstNumber() int {
    out := make(chan int)
    go numbers(out)

    return <-out // Return after receiving only the first value.
}

firstNumber returns after receiving 1. The producer then tries to send 2, but no receiver remains. Because out is unbuffered, that send blocks forever. defer close(out) does not help: the producer cannot reach its return statement while blocked on the send.

This pattern can be less obvious in real code. A caller may return after an HTTP timeout, a user may navigate away, or a worker may stop after seeing the first acceptable result. In all of those cases, the upstream goroutine needs to learn that its output is no longer wanted.

Use context cancellation so a producer can stop

context.Context gives a goroutine a cancellation signal that can be selected alongside a channel operation.

package main

import (
    "context"
    "fmt"
)

func numbers(ctx context.Context, out chan<- int) {
    defer close(out)

    for number := 1; number <= 3; number++ {
        select {
        case out <- number:
            // The consumer accepted this value.
        case <-ctx.Done():
            // The consumer no longer needs more values.
            return
        }
    }
}

func firstNumber() int {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // Also cancel if this function returns through another path.

    out := make(chan int)
    go numbers(ctx, out)

    first := <-out
    cancel() // Tell the producer not to send the remaining values.
    return first
}

func main() {
    fmt.Println(firstNumber())
}

The important part is the select. A plain out <- number can only wait for a receiver. The two-case select can instead stop when ctx.Done() becomes ready. Cancellation is cooperative: it does not forcibly kill a goroutine. Every blocking point that matters must check the cancellation signal or use an API, such as http.NewRequestWithContext, that observes it.

Avoid blocked result sends in a Go worker pool

The same issue appears when workers send results. A worker should not wait forever to send a result after its caller has timed out.

select {
case results <- result:
    // The collector accepted the completed result.
case <-ctx.Done():
    // The caller left, so do not remain blocked trying to report it.
    return
}

This is why the earlier worker-pool example checks ctx.Done() both while accepting jobs and while sending results. A buffered channel can reduce waiting, but it does not replace cancellation: once a buffer fills, a sender can still block. More importantly, a buffer does not tell a producer that its remaining work is no longer needed.

Channel ownership: decide who closes a channel

Closing a channel means “no more values will be sent.” The goroutine that produces those values is usually the right owner of close.

func produce(ctx context.Context, jobs chan<- string) {
    defer close(jobs) // This producer knows when there will be no more jobs.

    for _, job := range []string{"one", "two"} {
        select {
        case jobs <- job:
        case <-ctx.Done():
            return
        }
    }
}

Receivers normally do not close a channel, because they cannot know whether another sender is still working. Closing the same channel twice panics, and sending on a closed channel also panics. When multiple workers produce results, use a coordinator such as sync.WaitGroup: wait for every worker to finish, then close the shared results channel exactly once.

What is a data race in Go?

A data race happens when two goroutines access the same memory concurrently, at least one access writes, and the accesses are not correctly synchronized. The result may look correct during a local test and fail under a different load or CPU schedule.

Incrementing an integer is a classic example. total++ looks like one operation in source code, but it is a read, a calculation, and a write. Two goroutines can read the same old value and both write back the same new value.

package main

import (
    "fmt"
    "sync"
)

func main() {
    var total int
    var wg sync.WaitGroup

    for i := 0; i < 1_000; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            total++ // Unsafe: several goroutines write total together.
        }()
    }

    wg.Wait()
    fmt.Println(total)
}

The program may print 1000, or it may print a smaller number. Either outcome is not proof of safety. Run it with the race detector:

go run -race main.go
go test -race ./...

The detector instruments the program and reports many unsynchronized concurrent accesses. It is an excellent safety net, but it only reports races exercised by the test or program run. Keep tests concurrent enough to execute the paths you care about.

Fix shared counters with sync.Mutex

Use a sync.Mutex when several goroutines need to modify one shared, mutable value.

package main

import "sync"

type Counter struct {
    mu    sync.Mutex
    value int
}

func (counter *Counter) Increment() {
    counter.mu.Lock()
    defer counter.mu.Unlock()

    counter.value++
}

func (counter *Counter) Value() int {
    counter.mu.Lock()
    defer counter.mu.Unlock()

    return counter.value
}

The mutex protects the invariant: while one goroutine reads or changes value, another cannot enter a method protected by the same mutex. Keep the locked section small, and do not hold a mutex while making a slow network call or waiting for an unbounded external operation.

For simple counters, sync/atomic can also be appropriate. For a map plus related counts, a multi-field state change, or a rule that must be checked and updated together, a mutex often expresses the intent more clearly.

An alternative to a mutex: one goroutine owns the state

Channels are especially useful when one goroutine can own a piece of mutable state and other goroutines send it requests. That owner becomes the only code that touches the state directly.

type increment struct {
    reply chan int
}

func runCounter(requests <-chan increment) {
    total := 0 // Only this goroutine reads or writes total.

    for request := range requests {
        total++
        request.reply <- total
    }
}

func incrementCounter(requests chan<- increment) int {
    reply := make(chan int, 1)
    requests <- increment{reply: reply}
    return <-reply
}

This design avoids shared writes to total, but it is not automatically better than a mutex. It introduces a request channel, a lifecycle for the owner goroutine, and possible backpressure. Choose it when serial ownership matches the domain, such as a connection manager, an in-memory session loop, or a stateful actor-like component. Use a mutex when protected shared state is simpler.

Context cancellation is not durable job delivery

Cancellation is for work whose result is no longer needed. It is not a promise that work will finish later. If a request context is cancelled, a worker pool may stop and discard unfinished in-memory jobs by design.

For payment processing, required notifications, inventory changes, or other state-changing work that must eventually complete, persist the job and its status in a database or durable queue. Use idempotency keys so a retry can be safe even when the earlier attempt may have partly completed. This is a reliability boundary, not something a goroutine or a channel can provide by itself.

Go concurrency safety checklist

Give every goroutine a normal completion path and a cancellation path.
Use select with ctx.Done() around channel operations that could otherwise wait forever.
Decide which producer owns each close(channel) call.
Do not assume a channel buffer prevents leaks or proves completion.
Protect shared mutable state with a mutex, atomics, or single-goroutine ownership.
Run go test -race ./... in local development and CI.
Use a durable store and idempotency for work that must survive a process or request ending.

The goal is not to avoid goroutines or channels. It is to make their ownership, stopping behavior, and shared-state rules explicit. The official Go context documentation, race detector guide, and Go pipelines article are useful next references.

Kinmokusei

Nim Concurrency Explained: Async/Await, Threads, Channels, and Parallel Work

puffball1567 — Wed, 16 Sep 2026 13:18:19 +0000

Nim gives a program more than one way to work on several tasks at once. That is useful, but it also means that “parallel execution” is not one feature with one answer. A service waiting on many network requests needs a different model from an image-processing job that needs to use several CPU cores.

This article separates those cases. We will use Nim's standard asynchronous runtime for I/O-bound work, then look at native threads and channels for CPU-bound work. The goal is not to introduce concurrency everywhere; it is to choose a model that matches the work.

For a Go-oriented view of similar ideas, see Go Concurrency: How to Run Parallel Tasks with Goroutines, Channels, and Context.

Nim concurrency vs parallelism

Concurrency means a program can keep multiple tasks in progress. Parallelism means multiple tasks execute at the same moment on separate CPU cores. They often appear together, but they solve different bottlenecks.

If ten HTTP requests are waiting on remote servers, the bottleneck is mostly I/O. An event loop can let another request make progress while one is waiting, without giving each request a dedicated OS thread. If ten large images need to be resized, the bottleneck is CPU work. To use several cores, the program needs real parallel execution through threads or a task-pool library.

Workload	Start with	Why
HTTP, sockets, timers, file readiness	`asyncdispatch` and `async` / `await`	One event loop can manage many waiting operations efficiently.
CPU-heavy parsing, hashing, encoding, image work	threads or a maintained task-pool package	CPU work must run on separate threads to use more cores.
A long-running dedicated background task	`Thread` and `createThread`	The lifecycle and ownership are explicit.
Durable jobs that must survive restarts	A database or durable queue	Threads and channels alone do not persist unfinished work.

Nim async/await for I/O-bound concurrency

Nim's std/asyncdispatch provides an event loop and Future[T] values. Mark a procedure with {.async.} when it will suspend at await. Calling that procedure returns a future: a handle for a result that will become available later.

The following program starts two simulated network operations before waiting for either result. sleepAsync stands in for an operation such as an asynchronous HTTP request; it does not block the event loop while waiting.

import std/[asyncdispatch, strformat]

proc fetchPreview(url: string): Future[string] {.async.} =
  echo "starting ", url
  await sleepAsync(200) # Simulates waiting for network I/O without blocking the loop.
  return &"finished {url}"

proc main() {.async.} =
  # Both procedures reach their first await before main waits for a result.
  let first = fetchPreview("https://api.example.com/one")
  let second = fetchPreview("https://api.example.com/two")

  let previews = await all(first, second)
  for preview in previews:
    echo preview

waitFor main()

waitFor main() drives the event loop from a normal command-line program. In a server or GUI application, the application's existing event-loop integration determines where futures are awaited. The key point is that await yields control while an asynchronous operation is waiting, allowing other ready work on the same event loop to proceed.

This is concurrent I/O, not a promise that two CPU-intensive loops will run in parallel. Do not put a long CPU loop inside an async procedure and expect await elsewhere to make it responsive. The event loop only gets another opportunity to run when the current task reaches an awaitable operation.

A real Nim async HTTP example

Nim's standard library includes AsyncHttpClient for asynchronous HTTP work. The following example starts two GET requests, then waits for both response bodies.

import std/[asyncdispatch, httpclient]

proc fetchBody(client: AsyncHttpClient; url: string): Future[string] {.async.} =
  let response = await client.get(url)
  return await response.body

proc main() {.async.} =
  let client = newAsyncHttpClient()

  let first = fetchBody(client, "https://example.com")
  let second = fetchBody(client, "https://example.org")

  let bodies = await all(first, second)
  for body in bodies:
    echo body.len

waitFor main()

Treat a real client as a resource with a lifecycle. Set timeouts, limit how many operations you start at once, handle HTTP status codes and failures, and close or reuse clients according to the API you choose. Starting thousands of futures at once can still overload a remote service or consume too much memory. Async I/O removes the need for one thread per wait; it does not remove rate limits or capacity planning.

Native threads for CPU-bound parallel work in Nim

Nim's native threads are appropriate when work should occupy multiple CPU cores. A thread entry procedure is marked with {.thread.}, a Thread[T] value represents the running thread, and createThread starts it. joinThread waits for it to finish.

import std/[math, typedthreads]

type Work = tuple[startAt: int, endAt: int]

proc sumSquares(work: Work) {.thread.} =
  var total = 0.0
  for number in work.startAt..work.endAt:
    total += sqrt(number.float)
  echo total

var worker: Thread[Work]
createThread(worker, sumSquares, (1, 1_000_000))

# The main thread can perform other work here.
worker.joinThread()

Compile thread-based programs with thread support enabled:

nim c -r --threads:on app.nim

Current Nim documentation notes that --threads:on is enabled by default, but keeping the switch in an example makes the threading requirement visible and works with toolchains where it is not the default. A thread is much heavier than an async future. Do not create one native thread per input record; bound the number of active workers to the work and available CPU resources.

Pass thread results through a Nim channel

Nim's Channel[T] is designed for communication between Thread values. A sending thread places a value into the channel with send; the receiving thread obtains it with recv. The example below gives each worker an immutable range and returns its partial result through a module-level channel.

import std/[typedthreads, math]

type Work = tuple[startAt: int, endAt: int]
type PartialResult = tuple[startAt: int, total: float]

var results: Channel[PartialResult]

proc sumSquares(work: Work) {.thread.} =
  var total = 0.0
  for number in work.startAt..work.endAt:
    total += sqrt(number.float)

  results.send((work.startAt, total))

results.open()

var workers: array[2, Thread[Work]]
createThread(workers[0], sumSquares, (1, 500_000))
createThread(workers[1], sumSquares, (500_001, 1_000_000))

var combined = 0.0
for _ in 0..<workers.len:
  let partial = results.recv() # Wait for one worker result.
  combined += partial.total

for worker in workers.mitems:
  worker.joinThread()

results.close()
echo combined

The channel here is module-level on purpose. Nim's documentation explains that channels are safest when stored in process-wide shared memory; passing an ordinary heap-allocated channel to a thread through a pointer requires careful shared allocation. It also notes that values sent through channels are deeply copied and that cyclic data structures are not supported by the current message-passing implementation.

That means a good first thread design is usually: give a worker compact input data, let it create thread-local temporary state, and return a compact result. Avoid casually sharing a mutable seq, Table, ref object, or client instance between threads.

Locks and shared state: prefer ownership first

Threads create the possibility of simultaneous access to shared state. If two threads update the same counter, map, or object without synchronization, the result is a data race.

When a shared value is unavoidable, use the synchronization primitive that represents the rule. A Lock can protect a short, shared update.

import std/locks

var totalLock: Lock
var total: int

proc addToTotal(value: int) {.thread.} =
  acquire(totalLock)
  total += value
  release(totalLock)

initLock(totalLock)
# Create and join threads that call addToTotal here.
deinitLock(totalLock)

Keep the lock scope small. Do not acquire a lock and then make a network request, perform slow disk I/O, or wait for another unbounded operation. More importantly, consider whether the state needs to be shared at all. Passing results through a channel and combining them in one owner thread often produces a simpler design.

Nim additionally offers guards and lock annotations for selected shared locations. They can make intended locking rules visible and help the compiler check accesses. They are useful once a design genuinely needs shared state, but they are not a substitute for deciding ownership and lifecycle first.

Why the built-in Nim threadpool is not the default recommendation

You may find older Nim examples using std/threadpool, spawn, FlowVar, and parallel. They are part of Nim's history and still appear in documentation, but the current std/threadpool documentation marks the module deprecated and its API unstable. It recommends maintained Nimble packages such as malebolgia, taskpools, or weave instead.

That does not mean old code is automatically wrong. It means a new application should choose deliberately: use asyncdispatch for I/O concurrency, use Thread and Channel when a small number of dedicated native threads is enough, or evaluate a maintained task-pool package for a larger CPU work queue. Do not choose a thread pool only because an operation is asynchronous; first identify whether the bottleneck is waiting or computation.

Cancellation, retries, and durable work are separate concerns

An asynchronous operation or thread does not become a reliable background job merely because it runs outside the caller's immediate control. If a process exits, memory-only jobs and channels disappear. If an HTTP request is cancelled, it can be correct to stop optional work such as a page preview or a search suggestion.

For a payment, a required notification, or another state change that must eventually happen, persist the job state in a database or durable queue. Make retries idempotent, record whether an attempt may have completed, and make recovery possible after a restart. This is the same distinction that matters in Go worker pools: cancellation is for work that is no longer needed; durable delivery is for work that must not be lost.

A practical Nim concurrency checklist

Use async / await and asyncdispatch for I/O-bound waiting.
Use native threads only when CPU-bound work benefits from several cores or a task must have its own dedicated thread.
Do not block an event loop with long CPU work.
Bound concurrency; async futures and threads can both overwhelm a downstream service when created without limits.
Keep thread inputs and results small, explicit, and independent where possible.
Use Channel[T] for thread communication, and be careful about its copying and shared-memory rules.
Use locks only around short shared-state operations; prefer a single owner when that models the problem cleanly.
Do not use memory-only concurrency primitives as a durable queue.

Nim's official asyncdispatch documentation, thread manual section, channel documentation, and threadpool documentation are good references when choosing an implementation.

Related projects

KoutenDB — An open-source document and vector database written in Nim. Unlike a conventional relational database, it uses a locality-first retrieval model: related records are placed in application-defined ring coordinates, and that placement determines the initial retrieval scope, persistent disk locality, and cluster routing boundary. KoutenDB uses this model to begin from relevant local data instead of broadly reading unrelated data and filtering it afterward, aiming to reduce retrieval work and the candidate context sent to RAG or LLM systems.
Clay Board Style System — A CSS-inspired primitive engine for building expressive native GUI toolkits without a DOM or WebView. It lets applications keep component behavior in typed host-language code while sharing portable presentation across Nim, C++, and Rust.
Joubako — An application-facing asynchronous HTTP client for Nim. It uses standard Nim async foundations while adding typed results, retries, streaming, TLS, and production-oriented request controls.

Go Concurrency: How to Run Parallel Tasks with Goroutines, Channels, and Context

puffball1567 — Wed, 16 Sep 2026 08:20:56 +0000

Go is useful for backend services that need to wait on several slow operations at once. A service may call external HTTP APIs, read files, or handle queue messages. Instead of waiting for one operation to finish before starting the next, Go can let several tasks make progress together.

The first idea to learn is the goroutine: a lightweight unit of work managed by the Go runtime. We will begin with a small example of what go changes, then learn how channels let a program wait for a result. Only after those basics will we build toward timeouts and a worker pool.

Go concurrency vs parallelism

Concurrency means that a program can manage more than one task at a time. Parallelism means that two or more tasks are physically executing at the same instant on separate CPU resources. Goroutines express concurrency; the Go runtime and the machine determine how much actual CPU parallelism is available.

For many backend tasks, the immediate benefit is overlapping I/O. While one request waits for a network response, another request can continue. That does not mean every loop should create an unlimited number of goroutines.

What is a goroutine in Go?

A goroutine is a function call that Go can run independently from the function that started it. A normal function call waits until the called function returns. Put go before the same call, and the caller continues without waiting.

import (
    "fmt"
    "time"
)

func printTask(name string) {
    fmt.Println("finished:", name)
}

func main() {
    fmt.Println("main starts")

    go printTask("background task") // Start this task separately.

    fmt.Println("main keeps going") // This can run before printTask finishes.
    time.Sleep(10 * time.Millisecond) // Only for this small demonstration.
}

The order of the last two messages is not guaranteed. The important point is that main does not wait at go printTask(...). A Go program exits when main returns, even if another goroutine still has work to do. The time.Sleep line merely gives the background task time to print in this demonstration; it is not how production code should wait for goroutines.

The next section introduces channels, which give us a proper way to receive a result and know when a goroutine has finished.

Go channels: passing a value between goroutines

A channel is a typed path for values to travel between goroutines. Create one with make(chan Type).

messages := make(chan string) // This channel carries strings.

This form creates an unbuffered channel: a sender waits until another goroutine receives the value. make(chan Type, capacity) adds a buffer. The second argument is the number of values the channel may hold temporarily before a sender has to wait. For example, make(chan string, 3) can hold three strings.

The <- operator is used with channels. There are only two basic forms:

messages <- "hello"      // Send a string into the channel.
message := <-messages     // Receive the next string from the channel.

The arrow points to the value's destination. A receive waits until a value is available, which is helpful when one goroutine needs the result of another.

package main

import "fmt"

func main() {
    greetings := make(chan string) // A mailbox shared by two goroutines.

    go func() {
        // This runs separately from main.
        greetings <- "hello from another goroutine"
    }()

    // main waits here until the other goroutine sends its message.
    greeting := <-greetings
    fmt.Println(greeting)
}

WaitGroup and channels have different roles

sync.WaitGroup waits for a known group of goroutines to finish. It does not send results or errors; it only tracks whether work has completed.

var wg sync.WaitGroup

wg.Add(1) // We are about to start one goroutine.
go func() {
    defer wg.Done() // Mark this work as finished before returning.
    // Do one piece of work.
}()

wg.Wait() // Wait until every Add has a matching Done.

Channels move jobs and results. A wait group tells the coordinating code when every worker has finished and a result channel can safely close.

Go worker pool example: bounded parallel HTTP requests

Starting one goroutine for every URL can overload a remote API or use too much memory when the input is large. A worker pool starts a fixed number of workers instead. Each worker takes the next URL when it becomes free.

The following function fetches several URLs with at most workers requests in progress. The comments describe the purpose of each concurrency primitive.

package main

import (
    "context"
    "io"
    "net/http"
    "sync"
)

type FetchResult struct {
    URL    string
    Status int
    Body   []byte
    Err    error
}

func FetchAll(ctx context.Context, client *http.Client, urls []string, workers int) []FetchResult {
    if workers < 1 {
        workers = 1 // Always create at least one worker.
    }

    jobs := make(chan string) // URLs waiting to be fetched; sender and worker meet here.

    // The second make argument is the channel buffer size. At most one result
    // exists per URL, so len(urls) gives results room for every possible result.
    // Workers therefore do not need to wait for the collector after each fetch.
    results := make(chan FetchResult, len(urls))

    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1) // Register this worker before it starts.

        go func() {
            defer wg.Done() // Tell the coordinator this worker has stopped.

            for {
                select {
                case <-ctx.Done():
                    // The caller cancelled or timed out. Stop this worker.
                    return

                case url, open := <-jobs:
                    // Receiving from a closed channel returns open == false.
                    // That means the producer has no more URLs to send.
                    if !open {
                        return
                    }

                    result := fetchOne(ctx, client, url)

                    select {
                    case results <- result:
                        // Give the completed result to the caller.
                    case <-ctx.Done():
                        // Do not remain blocked if the caller has left.
                        return
                    }
                }
            }
        }()
    }

    go func() {
        // This goroutine produces jobs for the workers.
        defer close(jobs) // Closing jobs tells workers that production is over.

        for _, url := range urls {
            select {
            case jobs <- url:
                // Send one URL to whichever worker is ready.
            case <-ctx.Done():
                // Stop producing jobs when the caller cancels.
                return
            }
        }
    }()

    go func() {
        // Only close results after every worker has finished sending.
        wg.Wait()
        close(results)
    }()

    collected := make([]FetchResult, 0, len(urls))
    for result := range results {
        // range ends automatically after the results channel is closed.
        collected = append(collected, result)
    }
    return collected
}

func fetchOne(ctx context.Context, client *http.Client, url string) FetchResult {
    // Attach ctx so cancellation can stop the HTTP request too.
    request, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return FetchResult{URL: url, Err: err}
    }

    response, err := client.Do(request)
    if err != nil {
        return FetchResult{URL: url, Err: err}
    }
    defer response.Body.Close() // Release the HTTP connection when we are done.

    body, err := io.ReadAll(response.Body)
    return FetchResult{URL: url, Status: response.StatusCode, Body: body, Err: err}
}

select may look complex, but its job is simple: wait until one of several channel operations can proceed. Here, a worker either receives another URL or notices that cancellation was requested. Read case <-ctx.Done() as “stop when the caller says this work is no longer needed.”

Go context cancellation and timeouts in plain language

context.Context is a value passed along with an operation. It lets child work learn two things: whether the caller has cancelled, and whether the operation has reached its time limit.

This example creates a context with a three-second timeout:

import (
    "context"
    "time"
)

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel() // Release resources even when the timeout did not fire.

results := FetchAll(ctx, http.DefaultClient, urls, 8)

The 8 is a limit: no more than eight workers fetch URLs at once. It is not a magic performance value. Choose a limit based on the downstream API, connection pool, rate limits, memory cost, and whether the work is mostly I/O or CPU.

What cancellation means in this simple worker pool

The worker pool above is intentionally a simple, best-effort pattern. When its context is cancelled, it stops producing new jobs and asks workers to stop. Jobs that have not completed are not put back into the channel and are not retried. This is appropriate when the caller no longer needs the answer, such as collecting optional search results or data for a page the user has left.

It is not a durable queue. Unlike a system such as SQS, the in-memory jobs channel does not record acknowledgements, persist unfinished work, or make another worker retry a job after a process stops. Work that must happen exactly once or eventually happen, such as payment-related state changes or a required notification, needs a different implementation from the one above.

In an HTTP server, the handler receives the request as *http.Request. Call request.Context() to get the context that belongs to that specific client request, then pass it to the work started for that request.

func handleSearch(response http.ResponseWriter, request *http.Request) {
    // This context belongs to the current HTTP request.
    // It is cancelled if the client goes away.
    ctx := request.Context()

    urls := []string{
        "https://api.example.com/one",
        "https://api.example.com/two",
    }

    // FetchAll and every worker receive the same cancellation signal.
    results := FetchAll(ctx, http.DefaultClient, urls, 2)

    // Write results only if this handler still has a client to answer.
    if ctx.Err() == nil {
        json.NewEncoder(response).Encode(results)
    }
}

For request-scoped backend work, use request.Context() rather than creating context.Background() inside the handler. Background() has no connection to the client request, so child work would continue even after the client disconnects. The example assumes encoding/json and net/http are imported.

Go retry example: retry a failed read with a limit

Some practical tasks can retry a failure before returning it. For a read-only HTTP request, a small bounded retry loop can be reasonable when a temporary network error, rate limit, or server error occurs. The retry loop itself should still obey the same context, so it stops immediately when the caller cancels or the deadline expires.

import (
    "context"
    "net/http"
    "time"
)

func fetchWithRetry(ctx context.Context, client *http.Client, url string, maxAttempts int) FetchResult {
    var result FetchResult

    for attempt := 1; attempt <= maxAttempts; attempt++ {
        // Do not start another attempt after the caller has cancelled.
        if err := ctx.Err(); err != nil {
            return FetchResult{URL: url, Err: err}
        }

        result = fetchOne(ctx, client, url)
        if !shouldRetry(result) || attempt == maxAttempts {
            // Success, a non-retryable failure, or no attempts left.
            return result
        }

        // Wait a little longer after each failure: 200ms, 400ms, 600ms, ...
        delay := time.Duration(attempt) * 200 * time.Millisecond
        timer := time.NewTimer(delay)

        select {
        case <-ctx.Done():
            // Stop waiting and return the cancellation error immediately.
            timer.Stop()
            return FetchResult{URL: url, Err: ctx.Err()}
        case <-timer.C:
            // The delay ended; the loop starts the next attempt.
        }
    }

    return result // The loop always returns earlier; this keeps the compiler satisfied.
}

func shouldRetry(result FetchResult) bool {
    if result.Err != nil {
        return true // A temporary network error may succeed on a later attempt.
    }

    // Retry rate limits and server errors, but not ordinary client errors such as 404.
    return result.Status == http.StatusTooManyRequests || result.Status >= 500
}

To use this policy, replace fetchOne(ctx, client, url) in the worker with fetchWithRetry(ctx, client, url, 3). The number 3 is a policy decision, not a default that fits every API. A real client may also respect a Retry-After response header and add random jitter so many workers do not retry at the same moment.

Retry only operations whose repeated execution is safe. Retrying a GET request is usually easier to reason about than retrying a payment or a POST that creates a record. For state-changing work, use an idempotency key and persist job state in a database or durable queue. That lets a later worker distinguish “never started,” “may have completed,” and “needs another attempt.”

Avoid common Go concurrency mistakes

Limit work instead of creating one goroutine for every untrusted input item.
Decide which goroutine closes each channel. Usually it is the sender that knows there will be no more values.
Never close the same channel from multiple goroutines.
Give every goroutine a way to stop when its consumer leaves or its context is cancelled.
Use channels to hand values between goroutines. Use sync.Mutex when several goroutines must safely change the same shared value.
Run go test -race ./... regularly. The race detector can find accidental simultaneous access to shared memory.

The goal is not to create as many goroutines as possible. It is to make the number of active tasks, the cancellation behavior, and the owner of each result clear. The official Go context documentation, sync package documentation, and pipeline and cancellation article are useful next references.

Kinmokusei

How to Write Object-Oriented Code in Go: Structs, Methods, Interfaces, and Composition

puffball1567 — Mon, 14 Sep 2026 02:59:00 +0000

Go does not have classes or inheritance, but it does not prevent object-oriented design. It simply moves the building blocks into different language features: structs hold state, methods attach behavior, interfaces describe capabilities, and composition assembles collaborating parts.

The productive question is not “how can I recreate a class hierarchy in Go?” It is “which data owns this behavior, and which dependency should this component require?” This article builds a small application service around that question.

Start with data and behavior

Suppose an application lets a user change their display name. The domain value is a struct, while the operation belongs on a service that has access to user storage.

package users

import (
    "context"
    "errors"
)

type User struct {
    ID          int64
    DisplayName string
}

type Repository interface {
    FindByID(ctx context.Context, id int64) (User, error)
    Save(ctx context.Context, user User) error
}

type Service struct {
    repository Repository
}

func NewService(repository Repository) *Service {
    return &Service{repository: repository}
}

func (s *Service) Rename(ctx context.Context, id int64, name string) (User, error) {
    if name == "" {
        return User{}, errors.New("display name is required")
    }

    user, err := s.repository.FindByID(ctx, id)
    if err != nil {
        return User{}, err
    }

    user.DisplayName = name
    if err := s.repository.Save(ctx, user); err != nil {
        return User{}, err
    }
    return user, nil
}

User is a value with data. Service is a struct with a dependency and a cohesive operation. The constructor function makes the dependency explicit at creation time. None of these types needs a base class to have a clear responsibility.

Define interfaces where they are consumed

The Repository interface above belongs next to Service, not necessarily next to a database implementation. The service states the smallest capability it needs: load a user and save a user. Any type with those methods satisfies the interface automatically.

That has two useful consequences. Production code can use a PostgreSQL-backed repository, while a test can use a small in-memory fake. Neither implementation needs to import a shared “repository base class” or declare that it implements the interface.

type MemoryRepository struct {
    users map[int64]User
}

func (r *MemoryRepository) FindByID(_ context.Context, id int64) (User, error) {
    user, ok := r.users[id]
    if !ok {
        return User{}, errors.New("user not found")
    }
    return user, nil
}

func (r *MemoryRepository) Save(_ context.Context, user User) error {
    r.users[user.ID] = user
    return nil
}

This is dependency inversion without a framework. The application service depends on a capability, rather than on a particular storage driver.

Prefer composition to inheritance

Go supports struct embedding, but embedding is not a substitute for a deep inheritance tree. It promotes fields and methods from one struct into another; it does not give Go classes, virtual methods, or a general subtype model.

For backend code, explicit fields are usually clearer than embedding. If a service needs a clock, a logger, and an email sender, name them as dependencies:

type EmailSender interface {
    Send(ctx context.Context, to string, subject string, body string) error
}

type NotificationService struct {
    users UserLookup
    email EmailSender
}

This makes the object graph visible, keeps testing straightforward, and avoids coupling unrelated behavior through a shared parent type. Use embedding when the promoted behavior genuinely reads as part of the receiving type, not merely to reduce typing.

Keep interfaces narrow and delay abstraction

Not every struct needs an interface. A useful default is to create a concrete type first, then introduce an interface at the consumer boundary when a second implementation or a test seam actually exists.

Large interfaces tend to become accidental framework contracts. Small interfaces are easier to implement, easier to test, and clearer about what an operation needs. Go’s standard library follows this style: a type only needs to provide the methods required by the consumer.

A practical Go OOP checklist

Use structs to group state.
Attach behavior with methods when that behavior naturally belongs to the state or service.
Use constructor functions to make required dependencies explicit.
Define small interfaces at the point where they are consumed.
Prefer explicit composition to inheritance-shaped abstractions.
Pass context.Context through request-scoped backend operations.
Keep transport concerns such as HTTP request parsing outside domain services.

This approach is object-oriented in the useful sense: state, behavior, dependencies, and boundaries have clear ownership. It just does not require a class hierarchy to achieve it. The official Go documentation on methods and interfaces is a good companion when learning the language mechanics.

DEV Community: puffball1567

bgfx Instancing Tutorial: Draw 625 Cubes with One Draw Call

1. Sharing geometry did not combine the draw calls

2. What changes from the previous implementation

Use SDL3 for the window and input

3. Each cube only needs a center position

4. Allocate space for this frame

5. Write the placement records

6. Receive instance positions in the shader

7. Bind the list and submit once

8. Assemble the changes and verify the result

Fewer submissions do not imply a fixed speedup

Complete source by file

demo_support.h

main.cpp

shaders/varying.def.sc

shaders/vs_instanced.sc

shaders/vs_wave.sc

shaders/fs_wave.sc

shaders/vs_overlay.sc

shaders/fs_overlay.sc

make_overlay.py

build.sh

verify_instancing.py

Build and run the saved files

Clay Board Style System

Inside TypeScript 7: How the Compiler Finds Types You Never Wrote

Source and license note

Start with code that has no type annotations

Four objects to keep apart

From the name to the function being called

A Signature can exist before its return type is known

Compute the return type when it is needed

Build the type from return expressions

What if there are two return statements?

Where the inferred type is stored

What if reassignment changes the type at a later location?

Back to user.name.toUpperCase

What happens when the source code is edited?

What to borrow for application code

Example verification

Related project

Object-Oriented Programming for Beginners: Build a Character Health System

Start with variables and a function

Define a character with a class

Create two separate instances

Add methods that work on the character

Keep health changes within the rules

Save and run the complete program

Connect the vocabulary to the code

Build a Colorful Wave of Cubes on the GPU with bgfx

Representing 3D shapes with polygons

What runs on the CPU, and what runs on the GPU?

1. Project directory structure

2. Describe one cube

3. Give each cube a position

Start with grid indices

Turn each index into a center position

Move the whole cube to that position

4. Pass time into the shader

5. Calculate the wave at the cube's center

6. Move each vertex and project it

7. Give the wave color and depth

8. Submit the same mesh with different inputs

9. Build and run the source

Check the effect instead of trusting the picture

Where to take it next

Clay Board Style System

Inside TypeScript 7: Parallel Type Checking Without Giving Up Determinism

Source and license note

The problem: type checking has shared semantic work

A checker is a stateful worker, not just a goroutine

Why file assignment is a graph-partitioning problem

Determinism is part of the design, not a by-product

The worker count is a performance and memory dial

What application developers can borrow from this design

Closing thought

Related project

Further reading

Inside TypeScript 7: Arena Allocation and AST Memory Layout

`demo_support.h`

`main.cpp`

`shaders/varying.def.sc`

`shaders/vs_instanced.sc`

`shaders/vs_wave.sc`

`shaders/fs_wave.sc`

`shaders/vs_overlay.sc`

`shaders/fs_overlay.sc`

`make_overlay.py`

`build.sh`

`verify_instancing.py`

How TypeScript 7's `Arena` differs from a classic arena

What `NodeFactory.newNode` does

When does `OnCreate` run?

Step 5: the small example keeps `Kind` and data together