tessl/npm-angular--tsc-wrapped

Wraps the tsc CLI, allowing extensions.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@angular/tsc-wrapped

Name: tessl/npm-angular--tsc-wrapped
Author: tessl

@angular/tsc-wrapped is a TypeScript compiler wrapper library that extends TypeScript's tsc program with Angular-specific functionality. It provides a hook system for specific extensions developed by the Angular team, including tsickle for down-leveling Decorators into Annotations for tree-shaking compatibility, optional Closure Compiler-friendly code generation, and a metadata collector that emits .metadata.json files alongside .d.ts files to preserve decorator information lost during TypeScript compilation.

Package Information

Package Name: @angular/tsc-wrapped
Package Type: npm
Language: TypeScript
Installation: This is an internal dependency used by @angular/compiler-cli. Please use that instead.
Version: 0.0.0-PLACEHOLDER
Dependencies: tsickle ^0.21.0
Peer Dependencies: typescript ^2.1.5

Core Imports

import { 
  main, 
  CodegenExtension, 
  createBundleIndexHost, 
  UserError,
  MetadataWriterHost, 
  AngularCompilerOptions,
  MetadataCollector,
  MetadataBundler,
  DelegatingHost,
  SyntheticIndexHost,
  formatDiagnostics,
  isVinylFile,
  privateEntriesToIndex
} from "@angular/tsc-wrapped";

For CommonJS:

const { 
  main, 
  CodegenExtension, 
  createBundleIndexHost, 
  UserError,
  MetadataWriterHost, 
  AngularCompilerOptions,
  MetadataCollector,
  MetadataBundler,
  DelegatingHost,
  SyntheticIndexHost,
  formatDiagnostics,
  isVinylFile,
  privateEntriesToIndex
} = require("@angular/tsc-wrapped");

Basic Usage

import { main, AngularCompilerOptions } from "@angular/tsc-wrapped";

// Basic compilation with Angular options  
const angularOptions: AngularCompilerOptions = {
  genDir: "./generated",
  basePath: "./src",
  skipMetadataEmit: false,
  strictMetadataEmit: true
};

// Run compilation
await main("./tsconfig.json", { basePath: "./src" }, undefined, angularOptions);

Architecture

@angular/tsc-wrapped is built around several key components:

Main Compilation Pipeline: The main function orchestrates TypeScript compilation with Angular extensions
Metadata Collection: Emits .metadata.json files that preserve decorator information lost during TypeScript compilation
Bundle Index Generation: Creates flat module index files for library packaging
Compiler Host Extensions: Specialized compiler hosts for metadata writing and synthetic file handling
CLI Options System: Structured options for configuring Angular-specific compilation behavior
Schema System: Type definitions and validation for metadata structures
tsickle Integration: Down-levels decorators and provides Closure Compiler compatibility

Capabilities

Main Compilation Pipeline

Core compilation functionality that orchestrates TypeScript compilation with Angular-specific extensions.

function main(
  project: string | VinylFile, 
  cliOptions: CliOptions, 
  codegen?: CodegenExtension, 
  options?: ts.CompilerOptions
): Promise<any>;

interface CodegenExtension {
  (ngOptions: NgOptions, cliOptions: CliOptions, program: ts.Program, host: ts.CompilerHost): Promise<string[]>;
}

function createBundleIndexHost(
  ngOptions: NgOptions, 
  rootFiles: string[], 
  host: ts.CompilerHost
): {host: ts.CompilerHost, indexName?: string, errors?: ts.Diagnostic[]};

class UserError extends Error {
  constructor(message: string);
}

Main Compilation Pipeline

Metadata Collection System

Collects decorator metadata from TypeScript modules and emits .metadata.json files to preserve information lost during TypeScript compilation.

class MetadataCollector {
  constructor(options?: CollectorOptions);
  getMetadata(sourceFile: ts.SourceFile, strict?: boolean): ModuleMetadata;
}

interface CollectorOptions {
  version?: number;
  quotedNames?: boolean; 
  verboseInvalidExpression?: boolean;
}

Metadata Collection

Compiler Host Extensions

Specialized compiler hosts that extend TypeScript's standard compiler host with Angular-specific functionality.

class MetadataWriterHost extends DelegatingHost {
  constructor(delegate: ts.CompilerHost, ngOptions: NgOptions, emitAllFiles?: boolean);
}

abstract class DelegatingHost extends ts.CompilerHost {
  constructor(delegate: ts.CompilerHost);
}

class SyntheticIndexHost extends DelegatingHost {
  constructor(delegate: ts.CompilerHost, syntheticIndex: {name: string, content: string, metadata: string});
}

Compiler Host Extensions

Bundle Management

Bundles metadata from multiple modules and generates index files for library packaging.

class MetadataBundler {
  constructor(root: string, importAs?: string, host?: MetadataBundlerHost);
  getMetadataBundle(): BundledModule;
}

interface MetadataBundlerHost {
  getMetadataFor(moduleName: string): ModuleMetadata;
  resolveModule(moduleName: string, containingFile: string): string;
}

Bundle Management

Configuration Options

Angular compiler options and CLI options for configuring compilation behavior.

interface AngularCompilerOptions extends ts.CompilerOptions {
  genDir?: string;
  basePath?: string; 
  skipMetadataEmit?: boolean;
  strictMetadataEmit?: boolean;
  skipTemplateCodegen?: boolean;
  flatModuleOutFile?: string;
  flatModuleId?: string;
  generateCodeForLibraries?: boolean;
  annotateForClosureCompiler?: boolean;
  annotationsAs?: 'decorators' | 'static fields';
  trace?: boolean;
  enableLegacyTemplate?: boolean;
  enableSummariesForJit?: boolean; 
  alwaysCompileGeneratedCode?: boolean;
  preserveWhitespaces?: boolean;
}

Configuration Options

Metadata Schema

Type definitions and validation for metadata structures used throughout the system.

interface ModuleMetadata {
  __symbolic: 'module';
  version: number;
  metadata: {[name: string]: MetadataEntry};
  exports?: ModuleExportMetadata[];
  importAs?: string;
}

type MetadataEntry = 
  | ClassMetadata 
  | InterfaceMetadata 
  | FunctionMetadata 
  | MetadataValue;

Metadata Schema