Tspoon

1.0.460 verified Fri May 01 auth: no javascript

Tspoon is a library that provides AST visitors for TypeScript, enabling pluggable modifications to the abstract syntax tree before transpilation. Current stable version is 1.0.460, with active development. It leverages the TypeScript compiler API to allow custom visitors to transform code, perform early optimizations, and bypass diagnostics. Unlike general-purpose AST tools, Tspoon is specifically designed for TypeScript and integrates with its transpilation pipeline. Release cadence is irregular. Key differentiator: deep integration with TypeScript's compiler, supporting visitor composition and custom diagnostics.

Common errors

error Cannot find module 'tspoon' ↓

cause tspoon not installed or not in node_modules

fix

Run 'npm install tspoon'

error TypeError: node.kind is undefined ↓

cause Visitor filter called on null/undefined node due to improper traversal

fix

Check that traverse() is called with valid visitors and nodes; avoid calling filter on undefined nodes.

error The 'Visitor' interface is not exported from 'tspoon' ↓

cause Attempting to import Visitor in CommonJS without TypeScript type support

fix

Use TypeScript with ESM import: import type { Visitor } from 'tspoon'

Warnings

gotcha visitor filter method must return boolean; if omitted or returns falsy, visitor is skipped incorrectly. ↓

fix Always explicitly return true/false in filter.

gotcha context.replace with negative length can corrupt AST. ↓

fix Ensure end > start and use node.getStart() and node.getEnd() correctly.

gotcha TypeScript compiler version must match; tspoon uses compiler API symbols that may break across TS versions. ↓

fix Pin TypeScript version to one compatible with tspoon (check package peerDependencies).

deprecated The validate() method is experimental and may have breaking changes or be removed. ↓

fix Avoid using validate() in production; use transpile with custom diagnostics instead.

Install

npm install tspoon

yarn add tspoon

pnpm add tspoon

Imports

transpile

wrong

const tspoon = require('tspoon'); tspoon.transpile(...)

correct

import { transpile } from 'tspoon'

ESM import recommended. CommonJS require also works but not tree-shakable.

validate

wrong

const validate = require('tspoon').validate

correct

import { validate } from 'tspoon'

validate is still experimental; API may change.

Visitor

wrong

const { Visitor } = require('tspoon')

correct

import type { Visitor } from 'tspoon'

Visitor is an interface, type-only import in TypeScript.

Quickstart

Shows how to define a visitor that removes private properties and run transpile.

import { transpile } from 'tspoon';
import * as ts from 'typescript';

const code = `
class Foo {
    private x: number;
    constructor() { this.x = 42; }
}`;

const config = {
    sourceFileName: 'input.ts',
    visitors: [{
        filter(node) { return node.kind === ts.SyntaxKind.PropertyDeclaration && node.modifiers && node.modifiers.some(m => m.kind === ts.SyntaxKind.PrivateKeyword); },
        visit(node, context, traverse) { context.replace(node.getStart(), node.getEnd(), ''); context.reportDiag(node, ts.DiagnosticCategory.Message, 'deleted private field', false); }
    }]
};

const result = transpile(code, config);
console.log(result.code);