DEV Community: puffball1567

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.

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

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.

Kinmokusei

Kinmokusei v0.2.0: Generic OOP and Go Type Constraints for a TypeScript-Inspired Language

puffball1567 — Sat, 12 Sep 2026 18:37:19 +0000

Kinmokusei v0.2.0 expands the language in the places where application code and the Go ecosystem meet: generic object-oriented programming, generic constraints, type aliases, and JSON interop. Kinmokusei uses TypeScript-inspired syntax, but compiles to readable Go and uses the ordinary Go toolchain and package ecosystem directly. This release makes several of those boundaries more capable without treating generated Go as an opaque implementation detail.

Generic class inheritance and virtual dispatch

Classes in Kinmokusei are reference types. v0.2.0 adds generic class static methods, generic class inheritance, and generic virtual dispatch. A generic derived class can inherit a base class with concrete or remapped type arguments, retain the inherited state, and override a virtual member while preserving the expected dispatch behavior through the hierarchy.

That matters when a reusable abstraction carries its data type through more than one layer. A paged result, a domain-specific collection, or a typed application model should not need to discard its type parameter merely because it adds behavior in a derived class.

The release also adds descendant-aware class downcasts. A checked downcast can recover a more specific type within the same class hierarchy while keeping the failure path explicit, rather than silently assuming that every base-class value has the desired derived shape.

const [guide, ok] = animal as? GuideDog;
if (ok) {
  console(guide.speak());
}

The checked form returns a value together with a boolean result. It makes the runtime boundary visible at the call site, while reference identity and virtual dispatch remain part of the class model.

Use Go type-set constraints from Kinmokusei

Go libraries increasingly express generic capabilities through interface type sets. v0.2.0 lets Kinmokusei use exported constraints from the Go standard library and external Go modules, rather than limiting generic code to comparable.

For example, code can use a constraint such as cmp.Ordered when an operation really requires an ordered value:

import go cmp from "cmp";

function earlier<T extends cmp.Ordered>(left: T, right: T): boolean {
  return left < right;
}

This is useful because it keeps the constraint owned by the Go package that defines it. Kinmokusei code can participate in the same generic API shapes as Go code, instead of recreating a parallel constraint vocabulary.

Generic aliases without raising the minimum Go version

v0.2.0 also adds transparent generic aliases. An alias can give a reusable Kinmokusei name to a parameterized shape without introducing a new nominal type:

alias Values<T> = T[];
alias Lookup<K, V> = Map<K, V>;

The compiler expands a generic alias to its instantiated underlying type at generated-Go boundaries. That detail is important for compatibility: the emitted code remains usable with the project's Go 1.23 minimum instead of depending on later Go generic-alias declarations. Kinmokusei tooling still retains the source-level alias, while Go consumers see the concrete Go type they expect.

v0.2.0 also permits a native struct as the underlying representation of a distinct type. This gives application code a way to add nominal meaning to an existing value layout while keeping conversions explicit and retaining Go-compatible value behavior.

Stable JSON behavior for generic and inherited classes

JSON is often the point where a type system meets an external API, stored data, or a frontend. v0.2.0 stabilizes JSON interop for generic classes: public fields use stable Kinmokusei field names, inherited public state is included, and private or protected state is excluded.

Decoding into a class instance preserves the class's reference-oriented model. Constructor-created instances retain their identity and virtual dispatch behavior, rather than being reduced to an unstructured map at the application boundary. Where a wire format needs special initialization or a different representation, an application can still define its own JSON handling.

A release focused on typed boundaries

These features are connected by the same goal: carry useful type information across the boundaries that real Go applications need to cross. Generic classes can model reusable reference-oriented behavior, Go type sets make interop constraints available directly, generic aliases keep source code readable without increasing the Go version requirement, and stable JSON rules make external data handling predictable.

Kinmokusei v0.2.0 is available now. Developers with Go installed can try the release with:

go install github.com/puffball1567/kinmokusei/cmd/keika@v0.2.0
keika version

The compiler supports Go 1.23 through Go 1.27. The release notes, source, and executable examples are available in the Kinmokusei repository.

Introducing Kinmokusei: TypeScript-Inspired Syntax That Compiles to Readable Go

puffball1567 — Fri, 04 Sep 2026 16:31:55 +0000

On August 31, 2026, I released Kinmokusei v0.1.0, the first public preview of a programming language for writing web backends and Go libraries with TypeScript-inspired syntax and compiling them to readable Go source.

The compiler command is named keika, source files use the .km extension, and the generated program remains part of the ordinary Go ecosystem: it uses Go modules, the Go toolchain, the Go ABI, the Go runtime, and existing Go packages directly. Go—not TypeScript—is the compatibility target.

Repository: https://github.com/puffball1567/kinmokusei

What Kinmokusei is

Kinmokusei is a source language for the Go ecosystem. It resembles TypeScript, but it is not TypeScript. It is intended for developers who like TypeScript-shaped syntax but want to build and publish ordinary Go programs and libraries. Its syntax is the approachable frontend; Go is the platform underneath and the main compatibility boundary.

It is not a TypeScript-to-Go converter, transpiler, or TypeScript implementation. It does not accept .ts files or existing TypeScript projects and turn them into Go. It is also not Go source with alternate punctuation. Kinmokusei is a separate language with its own .km source, type system, and explicit constructs for behavior that must lower predictably to Go, including Go named types, pointers, multiple return values, interfaces, generics, channels, errors, and nil.

The central design choice is that generated Go is not a hidden temporary representation. It is deterministic, formatted with gofmt, readable by a Go developer, and suitable for inspection or publication.

.km source
    ↓ keika check / build / emit-go
readable Go source
    ↓ standard Go toolchain
native executable or Go library

Authors can distribute the .km source, the generated Go module, or both.

Go compatibility instead of npm compatibility

Kinmokusei deliberately does not target npm, Node.js, browser JavaScript, or the TypeScript package ecosystem. An npm package cannot be imported merely because the source looks similar to TypeScript, and JavaScript runtime behavior is not reproduced behind the generated program.

That is an intentional tradeoff rather than a missing transpiler feature. By giving up npm compatibility, the language can concentrate on Go compatibility: existing Go module graphs, exported package data, named types, pointers, structs, interfaces and method sets, multiple results, generics, channels, error, goroutines, the Go ABI, and the standard Go build toolchain.

The practical ecosystem escape hatch is therefore import go, not an npm compatibility layer. Higher-level Kinmokusei libraries can be built on that boundary, while the low-level types and behavior remain recognizable to Go developers.

A first program

The smallest program can import the real Go standard library through an explicit namespace:

import go fmt from "fmt";

function main(): void {
  fmt.Println("Hello from Kinmokusei");
}

Save this as hello.km, then check and run it:

keika check hello.km
keika run hello.km

keika emit-go hello.km prints the generated source:

// Code generated by Kinmokusei. DO NOT EDIT.
package main

import fmt "fmt"

func main() {
    fmt.Println("Hello from Kinmokusei")
}

There is no separate JavaScript runtime or compatibility layer in this path. The result is Go code that the normal Go toolchain can build.

TypeScript-inspired classes with Go underneath

Kinmokusei provides reference-type classes, interfaces, visibility, constructors, and explicit single inheritance. These features lower to Go structs, methods, embedding, and interfaces instead of introducing a second object runtime.

import { CounterValue } from "./counter-contract";

class Counter implements CounterValue {
  constructor(private value: int) {}

  public function increment(): void {
    this.value = this.value + 1;
  }

  public function current(): int {
    return this.value;
  }
}

Classes are reference types, while native struct declarations provide nominal Go-style value types with copy semantics. The language also includes interfaces, generic functions and types, fixed arrays and slices, maps, enums, defined types, nullable references, explicit Result<T> propagation, exceptions isolated from ordinary Go panics, channels, select, goroutines, and structured Task<T> values.

The aim is not to imitate every TypeScript or JavaScript behavior. The syntax should make the source approachable while preserving the distinctions that matter to generated Go, such as value versus reference semantics, copying versus aliasing, and a checked language null versus raw Go nil.

Use Go packages directly

The import go form is the low-level bridge to the Go ecosystem. It works with both the standard library and external modules:

import go gin from "github.com/gin-gonic/gin";
import go http from "net/http";

function NewRouter(): *gin.Engine {
  const router = gin.New();

  router.GET("/api/health", (ctx: *gin.Context): void => {
    ctx.JSON(http.StatusOK, {
      status: "ok",
      language: "Kinmokusei",
    });
  });

  return router;
}

The compiler reads exported Go package data and preserves Go types rather than flattening everything into a smaller foreign-function interface. Functions, constants, variables, structs, fields, methods, interfaces, pointers, multiple results, generics, callbacks, and explicit conversions are checked at the .km source location.

Kinmokusei can use an existing go.mod, or it can manage a locked module graph through its project manifest and lockfile. Normal checking and building validate that graph without silently updating dependencies.

Web backends are the first application target

The initial release focuses on web backends, Go library production, and goroutine-based workloads. The repository contains a JSON API built directly on net/http, an embedded HTTP package, and a full-stack example with one React and TypeScript frontend connected to interchangeable Gin and Fiber backends written in Kinmokusei.

Both framework examples call the real upstream Go packages. They compile into ordinary Go services and are tested against independently handwritten Go implementations of the same HTTP contract.

Kinmokusei also provides checked C boundaries for cases where Go is not the final consumer. Explicitly exported functions can produce a versioned C ABI, while incoming C FFI generation supports checked scalar, string, byte, array, struct, tagged-union, callback, error, handle, and ownership contracts.

The generated program must remain trustworthy

A source-to-source language can look convincing while small semantic differences accumulate underneath. Kinmokusei therefore keeps a registry of Go-equivalent runtime contracts. In v0.1.0, all 75 registered contracts have isolated differential tests against independently handwritten Go programs.

Generated programs are also compiled and tested across supported Go toolchains and target platforms. The release supports Go 1.23 through Go 1.27, and the published compiler is built with Go 1.27 so it can read export data produced by each supported toolchain.

This does not mean that Kinmokusei already covers the entire Go language or ecosystem. It means that accepted behavior is expected to be explicit, testable, and predictable instead of being passed through silently.

Compiler and editor support ship together

The keika distribution includes the compiler and keika lsp --stdio. The official Visual Studio Code extension is a thin client for that same language server, so diagnostics and semantic behavior stay aligned with the compiler version.

The current LSP provides diagnostics, hover, definition, references, rename, document symbols, completion, and signature help for Kinmokusei declarations and supported Go APIs. Matching VSIX files are attached to each release.

Try the public preview

Go 1.23 through Go 1.27 are supported. If Go is already installed, the tagged compiler can be installed with:

go install github.com/puffball1567/kinmokusei/cmd/keika@v0.1.0
keika version

Prebuilt archives for Linux, macOS, and Windows, checksums, and the matching Visual Studio Code extension are available on the v0.1.0 release page.

This is a pre-1.0 public preview. Source syntax and generated APIs may change between minor releases, and several areas remain intentionally incomplete. The current goal is to make the implemented boundary solid enough for real experiments, feedback, and incremental expansion.

If TypeScript-inspired source that produces readable Go sounds useful for a backend or library project, I would be glad to hear what you try, where the generated interface feels natural, and where it does not.

DEV Community: puffball1567

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

What problem is this arena solving?

Why care about individual heap allocations?

Source and license note

First, what an arena allocator usually means

How TypeScript 7's Arena differs from a classic arena

TypeScript 7 keeps an arena per selected node type

What NodeFactory.newNode does

When does OnCreate run?

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

What this memory layout guarantees

Why not put every node type in one arena?

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

Reference measurement: does the expected allocation effect appear?

Kinmokusei

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

Sources and scope

Jev in one sentence: state in, defined decisions out

Why this is not merely “LLM JSON mode”

Jev vs LLM: the practical comparison

A concrete example: triage, not customer support by itself

Where Jev is strong

Where an LLM remains the right tool

Strengths do not remove operational risk

The boundary to remember

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

Source and license note

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

Step 1: a parser needs more than the original text

Step 2: the simple approach is one large struct

Step 3: TypeScript can describe valid shapes with a union

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

Step 5: the small example keeps Kind and data together

What TypeScript-go adds beyond this small example

Does this AST design explain TypeScript 7's speed?

Reference measurement: traversal dispatch versus a flat struct

When is this pattern useful in an ordinary Go application?

Kinmokusei

Go Concurrency Safety: Prevent Goroutine Leaks and Data Races

What is a goroutine leak in Go?

A common Go channel leak: the consumer stops early

Use context cancellation so a producer can stop

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