compatfactory

A library that unifies the TypeScript Compiler API factory functions across all versions of TypeScript and makes them conform with the Node Factory API

Description

TypeScript's Compiler APIs are constantly evolving. With the release of TypeScript 4.0, the TypeScript team announced that they would move away from the old set of factory functions for creating and updating nodes, and over to a new Node Factory API. With the release of TypeScript 5.0, the old factory functions were removed entirely.

Nowadays, if you maintain a library or a tool that needs to work across multiple versions of TypeScript and you use any of TypeScript's Compiler APIs, you're going to have a really tough time. It will be error prone, difficult to read, and hard to maintain. There are many differences between the signatures of these methods across all versions of TypeScript, and many may not even exist.

This library exists to fix this problem. It simply provides a helper function, ensureNodeFactory, which takes a NodeFactory or a typescript object, and then returns an object conforming to the NodeFactory interface. In case a NodeFactory is passed to it, or if one could be found via the typescript.factory property, it will patch any inconsistencies there may be between the signatures of the factory functions across TypeScript versions and most often simply return the existing one with no further edits. For older TypeScript versions, it will wrap its factory functions with the new API such that you can simply use one API for all your operations! 🎉

Features

• A simple wrapper that enables you to use the most recent TypeScript Compiler API for every TypeScript version without having to worry about inconsistensies
• Tiny

Backers

Patreon

Table of Contents

• Description
  • Features
• Backers
  • Patreon
• Table of Contents
• Install
  • npm
  • Yarn
  • pnpm
  • Peer Dependencies
• Usage
• Contributing
• Maintainers
• License

Install

npm

$ npm install compatfactory

Yarn

$ yarn add compatfactory

pnpm

$ pnpm add compatfactory

Peer Dependencies

compatfactory depends on typescript, so you need to manually install this as well.

Usage

Simply import ensureNodeFactory and use it in place of the Node Factory you would otherwise be working with.

One very basic example could be:

import {ensureNodeFactory} from "compatfactory";

// Will use typescript.factory if available, and otherwise return an object that wraps typescript's helper functions
// but makes them conform with the Node Factory API
const factory = ensureNodeFactory(typescript);
factory.createClassDeclaration(/* ... */);

A more realistic example would be inside a Custom Transformer context:

import {ensureNodeFactory} from "compatfactory";
import type TS from "typescript";

function getCustomTransformers(typescript: typeof TS): TS.CustomTransformers {
	return {
		before: [
			context => {
				const factory = ensureNodeFactory(context.factory ?? typescript);

				return sourceFile => {
					return factory.updateSourceFile(
						sourceFile
						// ...
					);
				};
			}
		]
	};
}

Contributing

Do you want to contribute? Awesome! Please follow these recommendations.

Maintainers

Frederik Wessberg Twitter: @FredWessberg Github: @wessberg Lead Developer

License

MIT © Frederik Wessberg (@FredWessberg) (Website)

Changelog

4.0.1 (2024-09-24)

Bug Fixes

• handle export declarations on TS v4.8 and 4.9 (b05744c)

Features

• add TypeScript v5.2.2 compatibility (8090a3d)
• add TypeScript v5.3 support (4542219)
• add TypeScript v5.5 support (feefd1b)
• add TypeScript v5.6 support (e941e67)