CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-parcel--transformer-typescript-types

A Parcel transformer that processes TypeScript files to generate declaration files (.d.ts) with tree-shaking and module graph optimization

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

ts-compatibility.mddocs/

TypeScript Version Compatibility

Cross-version compatibility wrappers for TypeScript compiler API functions, ensuring consistent behavior across different TypeScript versions (3.0+).

Capabilities

Import Declaration Creation

Version-compatible wrappers for creating import-related AST nodes that work across different TypeScript compiler versions.

/**
 * Creates an import clause with version compatibility
 * @param factory - TypeScript node factory (or ts for older versions)
 * @param isTypeOnly - Whether this is a type-only import
 * @param name - Default import identifier (optional)
 * @param namedBindings - Named import bindings (optional)
 * @returns ImportClause AST node
 */
function createImportClause(
  factory: any,
  isTypeOnly: boolean,
  name: any,
  namedBindings: any
): any;

/**
 * Creates an import declaration with version compatibility
 * @param factory - TypeScript node factory (or ts for older versions)
 * @param modifiers - Declaration modifiers (optional)
 * @param importClause - Import clause (optional)
 * @param moduleSpecifier - Module path expression
 * @param assertClause - Import assertion clause (optional)
 * @returns ImportDeclaration AST node
 */
function createImportDeclaration(
  factory: any,
  modifiers: any,
  importClause: any,
  moduleSpecifier: any,
  assertClause: any
): any;

/**
 * Creates an import specifier with version compatibility
 * @param factory - TypeScript node factory (or ts for older versions)
 * @param isTypeOnly - Whether this is a type-only import specifier
 * @param propertyName - Original name in source module (optional)
 * @param name - Local binding name
 * @returns ImportSpecifier AST node
 */
function createImportSpecifier(
  factory: any,
  isTypeOnly: boolean,
  propertyName: any,
  name: any
): any;

Export Declaration Updates

Version-compatible wrapper for updating export declarations across TypeScript versions.

/**
 * Updates an export declaration with version compatibility
 * @param factory - TypeScript node factory (or ts for older versions)
 * @param node - Original export declaration to update
 * @param modifiers - Declaration modifiers (optional)
 * @param isTypeOnly - Whether this is a type-only export
 * @param exportClause - Named export bindings (optional)
 * @param moduleSpecifier - Re-export module path (optional)
 * @param assertClause - Export assertion clause (optional)
 * @returns Updated ExportDeclaration AST node
 */
function updateExportDeclaration(
  factory: any,
  node: any,
  modifiers: any,
  isTypeOnly: boolean,
  exportClause: any,
  moduleSpecifier: any,
  assertClause: any
): any;

TypeScript Version Support

Version Detection

The compatibility system detects TypeScript version at runtime:

const [majorVersion, minorVersion] = ts.versionMajorMinor
  .split('.')
  .map(num => parseInt(num, 10));

Supported Version Ranges

Each wrapper function supports specific TypeScript version ranges:

createImportClause Support

  • TypeScript 4.0+: factory.createImportClause(isTypeOnly, name, namedBindings)
  • TypeScript 3.8+: factory.createImportClause(name, namedBindings, isTypeOnly)
  • TypeScript 3.0+: factory.createImportClause(name, namedBindings) (no type-only support)

createImportDeclaration Support

  • TypeScript 4.8+: factory.createImportDeclaration(modifiers, importClause, moduleSpecifier, assertClause)
  • TypeScript 4.5+: factory.createImportDeclaration(undefined, modifiers, importClause, moduleSpecifier, assertClause)
  • TypeScript 3.0+: factory.createImportDeclaration(undefined, modifiers, importClause, moduleSpecifier)

createImportSpecifier Support

  • TypeScript 4.5+: factory.createImportSpecifier(isTypeOnly, propertyName, name)
  • TypeScript 3.0+: factory.createImportSpecifier(propertyName, name) (no type-only support)

updateExportDeclaration Support

  • TypeScript 4.8+: Full support for all parameters including assertion clauses
  • TypeScript 4.5+: Support without assertion clauses but with decorators parameter
  • TypeScript 4.0+: Support with type-only exports
  • TypeScript 3.8+: Basic support with different parameter order
  • TypeScript 3.0+: Basic support without type-only exports

Usage Examples

Generating Import Statements

import { 
  createImportClause, 
  createImportDeclaration, 
  createImportSpecifier 
} from '@parcel/transformer-typescript-types';

// Create named import: import { Button, Dialog } from 'components'
const importSpecifiers = [
  createImportSpecifier(factory, false, undefined, factory.createIdentifier('Button')),
  createImportSpecifier(factory, false, undefined, factory.createIdentifier('Dialog'))
];

const importClause = createImportClause(
  factory,
  false, // not type-only
  undefined, // no default import
  factory.createNamedImports(importSpecifiers)
);

const importDeclaration = createImportDeclaration(
  factory,
  undefined, // no modifiers
  importClause,
  factory.createStringLiteral('components'),
  undefined // no assertions
);

Updating Export Statements

import { updateExportDeclaration } from '@parcel/transformer-typescript-types';

// Update export to remove unused exports
const updatedExport = updateExportDeclaration(
  factory,
  originalExportNode,
  undefined, // modifiers
  false, // not type-only
  factory.createNamedExports(filteredExports), // only keep used exports
  undefined, // no module specifier
  undefined // no assertions
);

Implementation Details

Backward Compatibility Strategy

The wrappers use a cascade approach to handle version differences:

  1. Feature Detection: Check TypeScript version for feature availability
  2. Parameter Mapping: Map new parameter patterns to older API signatures
  3. Graceful Degradation: Fall back to simpler APIs when advanced features aren't available
  4. Error Handling: Throw assertion errors for unsupported versions

Factory vs Global API

The system handles both the modern factory-based API (TypeScript 4.0+) and the older global ts API:

// Modern factory API (preferred)
const node = factory.createImportClause(isTypeOnly, name, namedBindings);

// Legacy global API (fallback)
const node = ts.createImportClause(name, namedBindings);

Type-Only Import Evolution

The handling of type-only imports evolved across TypeScript versions:

  • TypeScript 3.8+: Introduced type-only imports with import type syntax
  • TypeScript 4.5+: Added type-only import specifiers
  • Earlier versions: No type-only support, parameters ignored

This ensures the transformer can generate appropriate import statements regardless of the TypeScript version in use.

Install with Tessl CLI

npx tessl i tessl/npm-parcel--transformer-typescript-types

docs

ast-processing.md

index.md

module-graph.md

transformer.md

ts-compatibility.md

tile.json