or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

exceptions.mdindex.mdlogging.mdmerging.mdutils.md
tile.json

tessl/npm-autorest--common

AutoRest common utilities for logging, configuration merging, exceptions, and styling

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@autorest/common@1.6.x

To install, run

npx @tessl/cli install tessl/npm-autorest--common@1.6.0

index.mddocs/

AutoRest Common

AutoRest Common provides essential utilities for the AutoRest code generation framework, including comprehensive logging infrastructure with configurable sinks and formatters, object merging functionality for configuration processing, exception handling utilities, and terminal styling features. This package serves as a foundational dependency for other AutoRest components, providing shared functionality for logging, configuration management, error handling, and user interface styling.

Package Information

  • Package Name: @autorest/common
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @autorest/common

Core Imports

import { 
  AutorestLogger, 
  LogLevel, 
  Exception, 
  strictMerge, 
  mergeOverwriteOrAppend, 
  isDefined, 
  color 
} from "@autorest/common";

CommonJS:

const { 
  AutorestLogger, 
  LogLevel, 
  Exception, 
  strictMerge, 
  mergeOverwriteOrAppend, 
  isDefined, 
  color 
} = require("@autorest/common");

Module-specific imports:

import { AutorestLogger, LogLevel } from "@autorest/common/dist/logging";
import { Exception } from "@autorest/common/dist/exceptions";
import { strictMerge } from "@autorest/common/dist/merging";
import { isDefined, color } from "@autorest/common/dist/utils";

Basic Usage

import { 
  AutorestSyncLogger, 
  ConsoleLoggerSink, 
  FilterLogger, 
  LogLevel,
  Exception,
  strictMerge,
  isDefined,
  color
} from "@autorest/common";

// Basic logging setup
const logger = new AutorestSyncLogger({
  sinks: [new ConsoleLoggerSink()],
  processors: [new FilterLogger({ level: "information" })]
});

logger.info("Processing started");
logger.trackError({ code: "E001", message: "Configuration error" });

// Configuration merging
const baseConfig = { timeout: 30, retries: 3 };
const userConfig = { retries: 5, debug: true };
const mergedConfig = strictMerge(baseConfig, userConfig);

// Utility functions
const validItems = [1, null, 3, undefined, 5].filter(isDefined); // [1, 3, 5]
const styledMessage = color("Processing **complete** with `success`");

// Exception handling
try {
  // Some operation
} catch (error) {
  throw new Exception("Operation failed", 1);
}

Architecture

AutoRest Common is built around four key modules:

  • Logging System: Multi-sink logging infrastructure with processors, formatters, and progress tracking
  • Exception Framework: Specialized exception classes for different error scenarios
  • Configuration Merging: Object merging utilities with macro interpolation support
  • Utility Functions: Type checking, array manipulation, and text styling helpers

Capabilities

Logging Infrastructure

Comprehensive logging system with multiple sinks, processors, formatters, and progress tracking capabilities. Supports both synchronous and asynchronous logging patterns with source enhancement and filtering.

interface AutorestLogger {
  debug(message: string): void;
  verbose(message: string): void;
  info(message: string): void;
  fatal(message: string): void;
  trackError(error: AutorestError): void;
  trackWarning(error: AutorestWarning): void;
  log(log: LogInfo): void;
  startProgress(initialName?: string): ProgressTracker;
  with(...processors: LoggerProcessor[]): AutorestLogger;
  diagnostics: AutorestDiagnostic[];
}

type LogLevel = "debug" | "verbose" | "information" | "warning" | "error" | "fatal";

Logging System

Exception Handling

Specialized exception classes for different error scenarios in AutoRest operations, including cancellation, abortion, and plugin errors.

class Exception extends Error {
  constructor(message: string, exitCode?: number);
  exitCode: number;
}

class OperationCanceledException extends Exception {
  constructor(message?: string, exitCode?: number);
}

class PluginUserError extends Error {
  constructor(pluginName: string);
  code: string; // "PluginUserError"
  pluginName: string;
}

Exception Handling

Configuration Merging

Advanced object merging utilities with macro interpolation support and configurable array merging strategies for configuration processing.

function strictMerge(a: any, b: any, path?: JsonPath): any;

function mergeOverwriteOrAppend(
  higherPriority: any,
  lowerPriority: any,
  options?: MergeOptions,
  path?: JsonPath
): any;

interface MergeOptions {
  interpolationContext?: any;
  arrayMergeStrategy?: ArrayMergingStrategy;
  concatListPathFilter?: (path: JsonPath) => boolean;
}

type ArrayMergingStrategy = "high-pri-first" | "low-pri-first";

Configuration Merging

Utility Functions

General-purpose utilities for type checking, array manipulation, and terminal text styling with markdown-like syntax support.

function isDefined<T>(value: T | undefined | null): value is T;

function arrayify<T>(value: T | T[] | undefined): T[];

function color(text: string): string;

Utility Functions

Types

Core types used across the API:

interface LogInfo {
  readonly level: LogLevel;
  readonly message: string;
  readonly code?: string;
  readonly source?: SourceLocation[];
  readonly details?: Error | unknown;
  readonly pluginName?: string;
  readonly extensionName?: string;
}

interface AutorestDiagnostic {
  level: Extract<LogLevel, "error" | "warning">;
  readonly code: string;
  readonly message: string;
  readonly source?: SourceLocation[];
  readonly details?: Error | unknown;
}

interface SourceLocation {
  readonly document: string;
  readonly position: Position | PathPosition;
}

interface Progress {
  current: number;
  total: number;
  name?: string;
}

interface ProgressTracker {
  update(progress: Progress): void;
  stop(): void;
}