tessl/npm-tsickle

Transpile TypeScript code to JavaScript with Closure annotations.

—

Pending

Overview

Eval results

Files

Module System Transformation

Name: tessl/npm-tsickle
Author: tessl

Converts CommonJS require() imports to goog.module() and goog.require() calls, with comprehensive support for ES6 module syntax transformation to Closure Compiler's module system.

Capabilities

CommonJS to goog.module Transformer

Main transformer that converts CommonJS and ES6 modules to Closure's goog.module format.

/**
 * Main transformer factory for CommonJS to goog.module conversion
 */
function commonJsToGoogmoduleTransformer(
  host: GoogModuleProcessorHost,
  modulesManifest: ModulesManifest,
  typeChecker: ts.TypeChecker
): ts.TransformerFactory<ts.SourceFile>;

Usage Example:

import { commonJsToGoogmoduleTransformer, ModulesManifest } from "tsickle";

const manifest = new ModulesManifest();
const host: GoogModuleProcessorHost = {
  pathToModuleName: (context, importPath) => importPath.replace(/\.tsx?$/, ''),
  fileNameToModuleId: (fileName) => fileName,
  isJsTranspilation: false
};

const transformer = commonJsToGoogmoduleTransformer(host, manifest, typeChecker);

Module Resolution

Functions for resolving and managing module names in the goog.module system.

/**
 * Resolves module names for goog.module
 */
function resolveModuleName(
  typechecker: ts.TypeChecker,
  node: ts.Node,
  pathToModuleName: (context: string, importPath: string) => string,
  host: ts.ModuleResolutionHost
): string | undefined;

/**
 * Gets namespace for import URL
 */
function namespaceForImportUrl(
  host: GoogModuleProcessorHost,
  context: string,
  importUrl: string
): string;

/**
 * Gets ambient module symbol
 */
function getAmbientModuleSymbol(
  typeChecker: ts.TypeChecker,
  moduleName: string
): ts.Symbol | undefined;

Module Marker Extraction

Utility for extracting module marker symbols from TypeScript library options.

/**
 * Extracts module marker symbols
 */
function extractModuleMarker(tsOptionsLib: readonly string[]): ts.Symbol[];

Module Comment Processing

Functions for handling existing goog.module comments and markers.

/**
 * Gets original goog.module name from comment
 */
function getOriginalGoogModuleFromComment(sourceFile: ts.SourceFile): string | undefined;

Configuration

GoogModuleProcessorHost Interface

Configuration interface for goog.module processing behavior.

interface GoogModuleProcessorHost {
  /** Converts import paths to module names */
  pathToModuleName(context: string, importPath: string): string;
  /** Converts file names to module IDs */
  fileNameToModuleId(fileName: string): string;
  /** Whether this is a JS transpilation (optional) */
  isJsTranspilation?: boolean;
}

Configuration Example:

const host: GoogModuleProcessorHost = {
  pathToModuleName: (context, importPath) => {
    // Convert relative imports to module names
    if (importPath.startsWith('./')) {
      return path.resolve(path.dirname(context), importPath).replace(/\.tsx?$/, '');
    }
    return importPath;
  },
  fileNameToModuleId: (fileName) => {
    // Convert file paths to module IDs
    return fileName.replace(/^\/project\/src\//, '').replace(/\.tsx?$/, '');
  },
  isJsTranspilation: false
};

Module Dependencies

ModulesManifest Class

Manages the module dependency graph of output JavaScript files.

/**
 * A class that maintains the module dependency graph of output JS files
 */
class ModulesManifest {
  /** Merges another manifest */
  addManifest(other: ModulesManifest): void;
  /** Registers a module */
  addModule(fileName: string, module: string): void;
  /** Adds module reference */
  addReferencedModule(fileName: string, resolvedModule: string): void;
  /** Gets filename from module name */
  getFileNameFromModule(module: string): string;
  /** Gets referenced modules */
  getReferencedModules(fileName: string): string[];
  /** All registered modules */
  get modules(): string[];
  /** All registered file names */
  get fileNames(): string[];
}

Usage Example:

const manifest = new ModulesManifest();

// Register modules
manifest.addModule('src/utils.js', 'app.utils');
manifest.addModule('src/main.js', 'app.main');

// Track dependencies
manifest.addReferencedModule('src/main.js', 'app.utils');

// Query dependencies
const dependencies = manifest.getReferencedModules('src/main.js');
console.log(dependencies); // ['app.utils']

FileMap Interface

Generic interface for file-based mappings.

interface FileMap<T> {
  [fileName: string]: T;
}

Transformation Examples

Import Statements

// Before transformation (TypeScript/ES6)
import { Component } from '@angular/core';
import * as utils from './utils';
import defaultExport from './default-export';

// After transformation (goog.module)
goog.module('app.component');

const Component = goog.require('angular.core.Component');
const utils = goog.require('app.utils');
const defaultExport = goog.require('app.default_export');

Export Statements

// Before transformation
export class MyClass {}
export const MY_CONSTANT = 'value';
export default function defaultFunction() {}

// After transformation
goog.module('app.my_module');

class MyClass {}
const MY_CONSTANT = 'value';
function defaultFunction() {}

exports.MyClass = MyClass;
exports.MY_CONSTANT = MY_CONSTANT;
exports = defaultFunction;

Dynamic Imports

// Before transformation
const module = await import('./dynamic-module');

// After transformation
const module = await goog.module.get('app.dynamic_module');

Module Namespace Handling

// Before transformation
import * as fs from 'fs';
fs.readFileSync('file.txt');

// After transformation
const fs = goog.require('node.fs');
fs.readFileSync('file.txt');