@remotex-labs/xmap
Version:
A library with a sourcemap parser and TypeScript code formatter for the CLI
427 lines (425 loc) • 11.3 kB
TypeScript
/**
* This file was automatically generated by xBuild.
* DO NOT EDIT MANUALLY.
*/
/**
* A callback function for formatting code lines
*
* @param lineString - The content of the line to be formatted
* @param padding - The amount of padding to be applied to the line
* @param line - The line number of the line to be formatted
* @returns Formatted line string
*
* @since 1.0.0
*/
type FormatCodeCallbackType = (lineString: string, padding: number, line: number) => string;
/**
* Configuration options for formatting code
*
* @since 1.0.0
*/
interface FormatCodeInterface {
/**
* The amount of padding to be applied to each line
* @since 1.0.0
*/
padding?: number;
/**
* The starting line number for formatting
* @since 1.0.0
*/
startLine?: number;
/**
* An optional action object specifying a line where a callback function should be triggered.
* @since 1.0.0
*/
action?: {
/**
* The line number at which the callback function should be triggered.
* @since 1.0.0
*/
triggerLine: number;
/**
* The callback function to be executed when the trigger line is encountered.
* @since 1.0.0
*/
callback: FormatCodeCallbackType;
};
}
/**
* Configuration for ANSI color styling of error pointers
* @since 1.0.0
*/
interface AnsiOptionInterface {
/**
* ANSI color code to apply to the error pointer
* @since 1.0.0
*/
color: ColorFunctionType;
}
/**
* A compact error position type used when only location and code metadata are needed.
*
* @remarks
* This type includes the source code content and the minimal location fields required
* to render or highlight an error snippet.
*
* @see PositionWithCodeInterface
* @since 1.0.0
*/
type ErrorCodeType = Pick<PositionWithCodeInterface, 'code' | 'line' | 'column' | 'startLine'>;
/**
* Represents a function that applies coloring or formatting to strings.
*
* @param args - Strings to be formatted
* @returns The formatted string
*
* @since 1.0.0
*/
type ColorFunctionType = (...args: Array<string>) => string;
/**
* Defines a color scheme for syntax highlighting various code elements.
*
* @remarks
* Each property is a {@link ColorFunctionType} that formats a specific type of syntax element,
* such as enums, classes, keywords, or literals.
*
* @see ColorFunctionType
* @since 1.0.0
*/
interface HighlightSchemeInterface {
/**
* Color function for enum names.
* @since 1.0.0
*/
enumColor: ColorFunctionType;
/**
* Color function for type names.
* @since 1.0.0
*/
typeColor: ColorFunctionType;
/**
* Color function for class names.
* @since 1.0.0
*/
classColor: ColorFunctionType;
/**
* Color function for string literals.
* @since 1.0.0
*/
stringColor: ColorFunctionType;
/**
* Color function for language keywords.
* @since 1.0.0
*/
keywordColor: ColorFunctionType;
/**
* Color function for comments.
* @since 1.0.0
*/
commentColor: ColorFunctionType;
/**
* Color function for function names.
* @since 1.0.0
*/
functionColor: ColorFunctionType;
/**
* Color function for variable names.
* @since 1.0.0
*/
variableColor: ColorFunctionType;
/**
* Color function for interface names.
* @since 1.0.0
*/
interfaceColor: ColorFunctionType;
/**
* Color function for function/method parameters.
* @since 1.0.0
*/
parameterColor: ColorFunctionType;
/**
* Color function for getter accessor names.
* @since 1.0.0
*/
getAccessorColor: ColorFunctionType;
/**
* Color function for numeric literals.
* @since 1.0.0
*/
numericLiteralColor: ColorFunctionType;
/**
* Color function for method signatures.
* @since 1.0.0
*/
methodSignatureColor: ColorFunctionType;
/**
* Color function for regular expressions.
* @since 1.0.0
*/
regularExpressionColor: ColorFunctionType;
/**
* Color function for property assignments.
* @since 1.0.0
*/
propertyAssignmentColor: ColorFunctionType;
/**
* Color function for property access expressions.
* @since 1.0.0
*/
propertyAccessExpressionColor: ColorFunctionType;
/**
* Color function for expressions with type arguments.
* @since 1.0.0
*/
expressionWithTypeArgumentsColor: ColorFunctionType;
}
/**
* Represents a segment of source code to be highlighted with specific styling.
*
* @remarks
* Segments are the fundamental units of the highlighting system.
* Each segment represents a portion of text that should receive specific styling.
* When the source code is processed for display,
* these segments are used to insert the appropriate color/style codes at the correct positions.
*
* The highlighter maintains a collection of these segments and applies them
* in position order to create the complete highlighted output.
*
* @example
* ```ts
* const keywordSegment: HighlightNodeSegmentInterface = {
* start: 0,
* end: 6,
* color: xterm.red
* };
* ```
*
* @see addSegment
* @see HighlightSchemeInterface
*
* @since 1.0.0
*/
interface HighlightNodeSegmentInterface {
/**
* The starting character position of the segment in the source text.
* @since 1.0.0
*/
start: number;
/**
* The ending character position of the segment in the source text.
* @since 1.0.0
*/
end: number;
/**
* The color or style code to apply to this segment.
* @since 1.0.0
*/
color: ColorFunctionType;
}
/**
* Represents a source map structure used for mapping code within a file to its original source
* @since 1.0.0
*/
interface SourceMapInterface {
/**
* The generated file's name that the source map is associated with
* @since 1.0.0
*/
file?: string | null;
/**
* An array of variable/function names present in the original source
* @since 1.0.0
*/
names?: Array<string>;
/**
* The version of the source map specification (standard is 3)
* @since 1.0.0
*/
version: number;
/**
* An array of URLs or paths to the original source files
* @since 1.0.0
*/
sources: Array<string>;
/**
* VLQ encoded string that maps generated code back to original source code
* @since 1.0.0
*/
mappings: string;
/**
* Root URL for resolving the sources
* @since 1.0.0
*/
sourceRoot?: string | null;
/**
* Array containing the content of the original source files
* @since 1.0.0
*/
sourcesContent?: Array<string>;
}
/**
* Represents a position in source code with mapping information
* @since 1.0.0
*/
interface PositionInterface {
/**
* Name of the identifier at this position
* @since 1.0.0
*/
name: string | null;
/**
* Line number in the original source
* @since 1.0.0
*/
line: number;
/**
* Column number in the original source
* @since 1.0.0
*/
column: number;
/**
* Path or URL to the original source file
* @since 1.0.0
*/
source: string;
/**
* Root URL for resolving the source
* @since 1.0.0
*/
sourceRoot: string | null;
/**
* Index of the source in the sources array
* @since 1.0.0
*/
sourceIndex: number;
/**
* Line number in the generated code
* @since 1.0.0
*/
generatedLine: number;
/**
* Column number in the generated code
* @since 1.0.0
*/
generatedColumn: number;
}
/**
* Position in source code including the original source content
*
* @see PositionInterface
* @since 1.0.0
*/
interface PositionWithContentInterface extends PositionInterface {
/**
* Content of the original source file
* @since 1.0.0
*/
sourcesContent: string;
}
/**
* Position in source code including code fragment information
*
* @see PositionInterface
* @since 1.0.0
*/
interface PositionWithCodeInterface extends PositionInterface {
/**
* Code fragment from the original source
* @since 1.0.0
*/
code: string;
/**
* Ending line number of the code fragment
* @since 1.0.0
*/
endLine: number;
/**
* Starting line number of the code fragment
* @since 1.0.0
*/
startLine: number;
}
/**
* Options for retrieving source code context
* @since 1.0.0
*/
interface SourceOptionsInterface {
/**
* Number of lines to include after the target line
* @since 1.0.0
*/
linesAfter?: number;
/**
* Number of lines to include before the target line
* @since 1.0.0
*/
linesBefore?: number;
}
/**
* Formats a code snippet with optional line padding and custom actions
*
* @param code - The source code | stack to be formatted
* @param options - Configuration options for formatting the code
* @returns A formatted string of the code snippet with applied padding and custom actions
*
* @remarks
* This function takes a code string and an options object to format the code snippet.
* It applies padding to line numbers and can trigger custom actions for specific lines.
* Options include padding (default 10), startLine (default 0), and custom actions for specific lines.
*
* @example
* ```ts
* const formattedCode = formatCode(code, {
* padding: 8,
* startLine: 5,
* action: {
* triggerLine: 7,
* callback: (lineString, padding, lineNumber) => {
* return `Custom formatting for line ${lineNumber}: ${lineString}`;
* }
* }
* });
* ```
*
* @since 1.0.0
*/
declare function formatCode(code: string, options?: FormatCodeInterface): string;
/**
* Formats a code snippet around an error location with special highlighting
*
* @param sourcePosition - An object containing information about the source code and error location
* @param ansiOption - Optional configuration for ANSI color codes
* @returns A formatted string representing the relevant code snippet with error highlighting
*
* @throws Error - If the provided sourcePosition object has invalid line or column numbers
*
* @remarks
* This function takes a sourcePosition object with code content and error location information,
* then uses formatCode to format and highlight the relevant code snippet around the error.
* The sourcePosition object should contain code (string), line (number), column (number),
* and optional startLine (number, defaults to 1).
*
* @example
* ```ts
* const formattedErrorCode = formatErrorCode({
* code: "const x = 1;\nconst y = x.undefined;\n",
* line: 2,
* column: 15,
* startLine: 1
* });
* ```
*
* @see formatCode - The underlying function used for basic code formatting
*
* @since 1.0.0
*/
declare function formatErrorCode(sourcePosition: PositionWithCodeInterface | ErrorCodeType, ansiOption?: AnsiOptionInterface): string;
export {
AnsiOptionInterface,
ErrorCodeType,
FormatCodeCallbackType,
FormatCodeInterface,
formatCode,
formatErrorCode
};