Inferring types from usage

2025-04-01T00:00:00+00:00

Membrane programs have a persistent state object that survives across deploys. You import it and use it like a regular JavaScript object:

import { state } from "membrane";

state.count ??= 0;

export function increment() {
  return ++state.count;
}

The entire JS heap is durable, but state is the conventional way to pass data between code versions. The question is: what type is state?

We could make developers define a State type for every program. But that’s boilerplate, and for quick scripts and prototypes it slows you down. We already had a TypeScript language service plugin for Membrane’s graph types, so I added state type inference to it.

The Idea

If you write state.count ??= 0, we know state.count is a number. If you write state.apiKey = args.apiKey and args.apiKey is a string, we know state.apiKey is a string. Walk the abstract syntax tree¹, find every assignment to a state property, extract the type from the right-hand side, and generate a type declaration.

The generated type looks like this:

type State = {
  count: number;
  apiKey: string;
  [key: string]: any;
};

That gets injected into the generated membrane.d.ts file. You get autocomplete and type checking on state without writing any type annotations. If you do want to define the type explicitly, export a State type or interface from index.ts and the inference backs off.

The Tricky Parts

The idea is simple, but as always implementation had more edge cases than expected.

Assignment Patterns

Turns out people assign to state in a lot of different ways:

state.count = 0; // direct assignment
state.count ??= 0; // nullish coalescing assignment
state.count ||= 0; // logical OR assignment
state.count += 1; // compound assignment
state.count = value as number; // type assertion

The AST visitor needs to catch all of these. Direct assignments and compound assignments (+=, -=, etc.) fall in a range of operator token kinds between FirstAssignment and LastAssignment, which makes them easy to handle together. Nullish coalescing assignment (??=) is its own token kind and needs a separate check:

if (
  ts.isBinaryExpression(node) &&
  node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
  node.operatorToken.kind <= ts.SyntaxKind.LastAssignment
) {
  processStateAssignment(node.left, node.right);
} else if (
  ts.isBinaryExpression(node) &&
  node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionEqualsToken
) {
  processStateAssignment(node.left, node.right);
}

Nullish Coalescing and `any`

state.count ??= 0 is interesting because the right-hand side is a binary expression with ??. The left side is state.count, which might be any if we haven’t inferred a type for it yet. The right side is 0, which is number.

If we naively get the type of the whole expression, TypeScript might give us any because one side is any. So we check both sides individually:

if (
  node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken ||
  node.operatorToken.kind === ts.SyntaxKind.BarBarToken
) {
  const leftType = checker.getTypeAtLocation(node.left);
  const rightType = checker.getTypeAtLocation(node.right);

  const isLeftAny = (leftType.getFlags() & ts.TypeFlags.Any) !== 0;
  const isRightAny = (rightType.getFlags() & ts.TypeFlags.Any) !== 0;

  if (isLeftAny && !isRightAny) return rightType;
  if (!isLeftAny && isRightAny) return leftType;

  return checker.getTypeAtLocation(node);
}

If one side is any and the other is concrete, use the concrete type. If both are concrete, use the union. This is what makes state.count ??= 0 correctly infer number instead of any.

Explicit vs Inferred Priority

Consider this:

state.count ??= 0; // inferred: number
state.count = getCount(); // explicit: number (from getCount's return type)

Both assignments tell us state.count is a number, but they have different confidence levels. A direct assignment (=) is explicit. A nullish coalescing assignment (??=) or logical OR assignment (||=) is inferred, because they’re fallback patterns that might not represent the primary type.

When we see a new assignment to a property we’ve already typed, explicit assignments override inferred ones. More specific types override any. This means the order of assignments in your code doesn’t matter as much as the kind of assignment.

Type Assertions

If you write state.data = response as ApiResponse, the type should be ApiResponse, not whatever TypeScript infers from response. The plugin checks for as expressions and type assertion expressions, unwrapping parenthesized expressions along the way:

function getAssertedType(node: Expression): Type | undefined {
  if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)) {
    return checker.getTypeAtLocation(node);
  }
  if (ts.isParenthesizedExpression(node)) {
    return getAssertedType(node.expression);
  }
  // ...
}

How It Fits Together

The inference hooks into getSemanticDiagnostics. Every time the editor updates diagnostics, the plugin walks the AST, collects state assignments, and generates the State type string. If it changed since last time, membrane.d.ts gets regenerated.

If a developer exports their own State type:

export interface State {
  count: number;
  apiKey: string;
}

The plugin detects that and imports it instead of generating one. Explicit always wins.

The General Problem

The technique here isn’t specific to state. It’s a general approach: infer the type of an untyped object by walking all the places it’s assigned to across a codebase. You could apply the same pattern to config objects, environment variables, feature flags, or any global singleton that accumulates properties over time.

TypeScript itself has open issues requesting “infer type from usage” for implicit any parameters, but it’s scoped to a single function body, not whole-program analysis. Flow does whole-program type inference, but that’s an entire type system. TypeStat infers types from usage patterns and writes annotations back into source files, but it targets individual variables and parameters, not a shared object.

The architecture closest to ours is Volar (Vue Language Tools), which generates virtual TypeScript files from .vue single-file components. The pattern is the same: take a non-standard source of type information, generate a .d.ts that the TypeScript language service can understand, and keep it updated as the source changes.

We’re doing a narrower version of that. Walk assignments to one object, build a type from what we find, inject it into a generated declaration file.

What I Learned

Working on this gave me a better feel for TypeScript’s compiler API than anything else I’ve done. The TypeChecker is powerful but not always intuitive. getTypeAtLocation can return any in cases where you’d expect something more specific, especially when the thing you’re checking is a property of an untyped object (which state is, until we infer its type). The getBaseTypeOfLiteralType call is important too. Without it, state.count = 0 would infer the literal type 0 instead of number.

The biggest takeaway: type inference is a game of priorities! You have multiple sources of type information (direct assignments, fallback patterns, type assertions, compound assignments) and you need rules for which one wins. Getting those priority rules right is what makes the experience feel natural instead of surprising.

Abstract Syntax Tree, a tree representation of source code structure.↩︎

typescript membrane

Thomas Seeley

@tseeley.com on Bluesky, @iamseeley on Mastodon

← How To Onboard · Hello, Membrane →

Maze Playground

2024-08-22T00:00:00+00:00

I read Andrew Healey’s Generating Mazes and wanted to see the algorithms work. Not just the finished maze, but each step of the generation. Walls getting removed one at a time, the path carving through the grid.

So I built a small playground for it. Deno, TypeScript, and a <canvas>.

The Data Model

A maze is a grid of cells. Each cell has four walls and knows whether it’s been visited.

export class Cell implements CellInterface {
  position: Position;
  hasTopWall: boolean;
  hasRightWall: boolean;
  hasBottomWall: boolean;
  hasLeftWall: boolean;
  visited: boolean;

  removeWall(neighbor: CellInterface): void {
    const dx = neighbor.position.x - this.position.x;
    const dy = neighbor.position.y - this.position.y;

    if (dx === 1) {
      this.hasRightWall = false;
      neighbor.hasLeftWall = false;
    }
    // ... and so on for each direction
  }
}

removeWall figures out which direction the neighbor is in and removes the wall on both sides. That’s the core operation of maze generation: two cells become connected.

Generators for Stepping

The part I liked most was using JavaScript generators for the algorithms. DFS yields after each step, which means the UI can consume it at whatever pace it wants.

*generateSteps(maze: MazeInterface, startCell: CellInterface): Generator<{ currentCell: CellInterface }> {
  const stack: CellInterface[] = [startCell];
  startCell.visited = true;

  while (stack.length > 0) {
    const currentCell = stack[stack.length - 1];
    yield { currentCell };

    const unvisitedNeighbors = maze.getNeighbors(currentCell)
      .filter(neighbor => !neighbor.visited);

    if (unvisitedNeighbors.length > 0) {
      const randomIndex = Math.floor(Math.random() * unvisitedNeighbors.length);
      const chosenNeighbor = unvisitedNeighbors[randomIndex];
      currentCell.removeWall(chosenNeighbor);
      chosenNeighbor.visited = true;
      stack.push(chosenNeighbor);
    } else {
      stack.pop();
    }
  }
}

The UI runs a setInterval at 50ms that calls generator.next(), snapshots the maze state, and renders it. After generation is done, a slider lets you scrub back through every step. You can watch the algorithm think.

What’s There, What’s Not

Right now only DFS is implemented. The dropdown lists Aldous-Broder, Prim’s, and Kruskal’s but they’re stubs. I’d like to add them eventually because the interesting thing about maze algorithms is how different the mazes feel. DFS creates long winding corridors with few branches. Aldous-Broder creates more uniform, random-looking mazes. Same grid, different character.

The rendering is simple Canvas drawing. Visited cells get a gray fill, the current cell gets a blue highlight, and walls are just lines. Nothing fancy, but it’s enough to see what’s happening.

typescript algorithms

Thomas Seeley

@tseeley.com on Bluesky, @iamseeley on Mastodon

← Neovim Cheatsheet · Scheme-ing →

Thomas Seeley - typescript

Inferring types from usage

Maze Playground