Thomas Seeley - membrane

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 · We forked TypeScript →

We forked TypeScript

2025-03-10T00:00:00+00:00

At Membrane, we forked TypeScript to extend contextual typing so our programming model gets type inference for free.

The changes were made by Juan Campa. I went through them recently while updating our fork to the latest TypeScript version. What I found was surprisingly small and worth explaining.

What Is Contextual Typing

Most type inference works bottom-up. You write let x = 42 and the compiler infers number from the value. Contextual typing works top-down. The compiler looks at where an expression appears and infers types from the surrounding context.

You’ve seen this in TypeScript even if you didn’t know the name:

// TypeScript knows `e` is MouseEvent from addEventListener's signature
window.addEventListener("click", (e) => {
  console.log(e.clientX);
});

// TypeScript knows `x` is a string from the array type
["a", "b", "c"].map((x) => x.toUpperCase());

The type flows down from the context into the expression. You don’t annotate the callback parameters because the compiler already knows what they should be.

This isn’t unique to TypeScript. Swift does it for closures. Kotlin infers lambda parameter types from the expected function type. C# has target-typed new expressions and lambda inference. Scala has its own flavor called “colored local type inference.” The theoretical foundation is bidirectional typing, which combines bottom-up synthesis with top-down checking.

Where TypeScript’s Contextual Typing Stops

Contextual typing in TypeScript works for callbacks, assignment right-hand sides, object literal members, array elements, and return statements. It does not work for top-level exported function declarations or variable declarations against an external type.

This means if you have a type somewhere that describes the shape of a function, and you write a top-level export function that should match it, TypeScript won’t infer the parameter types. You have to annotate them manually.

// These types exist somewhere
type ConfigureArgs = { schema: Schema };
type Configure = (args: ConfigureArgs) => void;

// TypeScript does NOT infer `args` here
export function configure(args) {
  // args is implicitly `any`
}

// You have to do this instead
export function configure(args: ConfigureArgs) {
  // now args is typed
}

For most codebases this is fine. For Membrane, it’s the core of the developer experience.

Membrane’s Programming Model

Membrane programs are durable TypeScript programs that expose their data and functionality through a type-safe graph. Each program has a schema (defined in memconfig.json) that declares its node types with fields, actions, and events. Think of it like a GraphQL schema for your program’s API.

Every program has an index.ts that exports resolvers: functions and objects that implement the schema. When someone queries a node in the graph, Membrane invokes the corresponding resolver to produce the value.

A typical index.ts looks like this:

import { state, nodes, root } from "membrane";

export const Root = {
  status() {
    return "ready";
  },
  configure,
  emails: () => ({}),
};

export const EmailCollection = {
  async one({ id }) {
    return await api("GET", `emails/${id}`);
  },
  async page() {
    const result = await api("GET", "emails");
    return { items: result.data };
  },
};

export const Email = {
  gref(_, { obj }) {
    return root.emails.one({ id: obj.id });
  },
  async cancel(_, { self }) {
    const { id } = self.$argsAt(root.emails.one);
    return api("POST", `emails/${id}/cancel`);
  },
};

Every one of those exported objects and functions needs to match the schema’s type definitions. The types are generated into a membrane.d.ts file and live in a global resolvers namespace. Without the fork, every resolver would need explicit type annotations. With dozens of resolvers per program, that’s a lot of boilerplate. And if the schema changes, every annotation needs updating.

We wanted the types to flow automatically: define the schema once, and the implementations get typed from context.

The Fork

The entire fork is about 70 lines of changes in src/compiler/checker.ts. No parser changes, no new syntax, no emitter modifications. Three commits, all by Juan.

The changes do three things:

1. Identify Membrane resolvers. Three helper functions check whether a declaration is an exported, top-level, named function or variable in an index.ts file:

function isMembraneFunctionResolver(node: FunctionDeclaration) {
  return (
    isInIndexTs(node) &&
    isInTopLevelContext(node) &&
    hasSyntacticModifier(node, ModifierFlags.Export) &&
    node.name &&
    isIdentifier(node.name)
  );
}

function isInIndexTs(node: Node): boolean {
  const sourceFile = getSourceFileOfNode(node);
  return !!sourceFile && /\/[^/]+\/index\.ts$/.test(sourceFile.fileName);
}

2. Look up the contextual type. When the checker encounters a qualifying declaration, it looks up the function or variable name in the global resolvers namespace and uses the matching type:

// For variable declarations like: export const Root = { ... }
const ns = globals.get(escapeLeadingUnderscores("resolvers"));
const exports = ns && getExportsOfSymbol(ns);
const exportSymbol = exports?.get(declaration.name.escapedText);
const typeAlias = exportSymbol && exportSymbol.declarations![0];
const type = typeAlias && getTypeFromTypeNode(typeAlias.type);
return type;

3. Mark exported functions as context-sensitive. Standard TypeScript only considers function expressions, arrow functions, and object literal methods as context-sensitive. The fork adds exported functions in index.ts to that set, which is what makes the checker attempt contextual typing for them at all:

function isContextSensitiveFunctionOrObjectLiteralMethod(func) {
  const isMembraneExport =
    hasSyntacticModifier(func, ModifierFlags.Export) && isInIndexTs(func);
  return (
    isMembraneExport ||
    ((isFunctionExpressionOrArrowFunction(func) ||
      isObjectLiteralMethod(func)) &&
      isContextSensitiveFunctionLikeDeclaration(func))
  );
}

That’s it. If there’s no global resolvers namespace, all the guards return early and standard TypeScript behavior applies. The changes are purely additive.

What It Looks Like

Before the fork, a Membrane index.ts would need explicit annotations everywhere:

import { state, nodes, root } from "membrane";

export function configure(args: ConfigureArgs): void {
  state.apiKey = args.apiKey;
}

export const Root: RootResolvers = {
  status(): string {
    return state.apiKey ? "ready" : "not configured";
  },
  emails: () => ({}),
};

export const EmailCollection: EmailCollectionResolvers = {
  async one({ id }: { id: string }) {
    return await api("GET", `emails/${id}`);
  },
};

export const Email: EmailResolvers = {
  gref(_, { obj }: { obj: any }) {
    return root.emails.one({ id: obj.id });
  },
};

After the fork:

import { state, nodes, root } from "membrane";

export function configure(args) {
  state.apiKey = args.apiKey;
}

export const Root = {
  status() {
    return state.apiKey ? "ready" : "not configured";
  },
  emails: () => ({}),
};

export const EmailCollection = {
  async one({ id }) {
    return await api("GET", `emails/${id}`);
  },
};

export const Email = {
  gref(_, { obj }) {
    return root.emails.one({ id: obj.id });
  },
};

Same code, no annotations. The types are inferred from the schema. You get autocomplete, error checking, and hover information. If the schema changes (say you add a subject field to Email), the resolver types update automatically. No manual syncing.

Why Fork Instead of…

The obvious question: why not use satisfies, explicit annotations, or a code generation step?

satisfies works for objects (export const Root = { ... } satisfies RootResolvers) but not for function declarations. It also requires the developer to remember to add it. We wanted types to flow automatically from the schema with no ceremony.

Code generation (generating annotated stubs from the schema) adds a build step and creates files the developer has to maintain alongside the schema. We wanted the source of truth to be the schema alone.

A TypeScript language service plugin could provide autocomplete but can’t add real type checking. We wanted both.

Forking the compiler was the cleanest path. ~70 lines, scoped to index.ts files in the presence of a resolvers namespace, no impact on non-Membrane code. The tradeoff is maintaining the fork across TypeScript releases, which is what I was doing when I decided to write this post.

Maintaining the Fork

Updating the fork means rebasing our changes onto the latest TypeScript release. Since the changes are small and concentrated in one file, this has been straightforward so far. The checker’s internal API does change between versions, so some adaptation is needed, but the core pattern (look up a name in a namespace, return its type) stays stable.

The bigger risk is if TypeScript ever adds native support for this kind of module-level contextual typing. That would be great, actually. We’d happily drop the fork. There are open issues requesting more contextual typing for function return values, and the general direction of TypeScript’s inference has been to expand where context flows. But top-level declarations against a global type namespace isn’t on the roadmap as far as I know.

Until then, ~70 lines in the checker gets us what we need.

typescript membrane

Thomas Seeley

@tseeley.com on Bluesky, @iamseeley on Mastodon

← Inferring types from usage · How to Use Chrome DevTools →

Hello, Membrane

2024-11-10T00:00:00+00:00

It’s been a busy, exciting past few months. I joined membrane.io as an intern in September, and I’m having a great time making improvements to the platform and building things in user space.

What’s Membrane?

Membrane is a serverless platform for developing JavaScript/TypeScript programs.

Every program you create in your Membrane workspace becomes part of your graph, and the programs can connect to each other through this graph.

There are a few key things that set Membrane apart from other serverless platforms:

Programs have built-in state - no need to set up a database
Everything gets logged before it happens - if it’s not in the logs, it didn’t happen
Each program gets an email address - handle incoming emails by exporting an email function
Each program gets its own endpoint - handle HTTP requests by exporting an endpoint function
Programs can use other programs as building blocks through graph connections

What I’ve Been Working On.

Most of my time has been spent on Membrane’s API drivers. Drivers let you interact with external APIs through Membrane’s graph.

I’ve been improving existing drivers like Discord and Anthropic and building a tool to generate new ones. The more drivers on Membrane, the more useful tools and automations we can build!

A driver exposes API endpoints as nodes (fields, actions, events) that you can reference in your graph with a simple syntax.

For example, github:users.one(name:"membrane-io") tells Membrane to get a specific GitHub user - but here’s what’s cool: even though that API call returns all of the user’s data, you can selectively reference just the pieces you need in other programs, like if we want to get their avatar: github:users.one(name:"membrane-io").avatar_url.

Other Projects and Improvements:

Implemented type inference for Membrane state
Dynamic OG images for the changelog, packages, and docs
Made a driver for the Membrane API: mem

I’m excited to start building more drivers and example tools/automations :).

If you’d like to learn more about Membrane check these out:

And join the Discord!

Want to Help Shape Membrane?

We’re looking for developers to try out Membrane and share their feedback!

If you’re interested in participating in user interviews, reach out to me at thomas@membrane.io. We’d love to hear your thoughts and help you get started building tools for yourself or for your company.

membrane javascript

Thomas Seeley

@tseeley.com on Bluesky, @iamseeley on Mastodon

← How to Use Chrome DevTools · Neovim Cheatsheet →