Struct NativePositionMapper 

pub struct NativePositionMapper { /* private fields */ }

Bidirectional position mapper for translating between original and expanded source positions.

This mapper enables IDE features like error reporting, go-to-definition, and hover to work correctly with macro-expanded code by translating positions between the original source (what the user wrote) and the expanded source (what the compiler sees).

Performance

Position lookups use binary search for O(log n) complexity, where n is the number of mapping segments. This is critical for responsive IDE interactions.

Example

const mapper = new PositionMapper(sourceMapping);

// Convert original position to expanded
const expandedPos = mapper.original_to_expanded(42);

// Convert expanded position back to original (if not in generated code)
const originalPos = mapper.expanded_to_original(100);

// Check if a position is in macro-generated code
if (mapper.is_in_generated(pos)) {
    const macro = mapper.generated_by(pos); // e.g., "Debug"
}

Implementations

impl NativePositionMapper

pub fn new(mapping: SourceMappingResult) -> Self

Creates a new position mapper from source mapping data.

Arguments

• mapping - The source mapping result from macro expansion

Returns

A new NativePositionMapper ready for position translation.

pub fn is_empty(&self) -> bool

Checks if this mapper has no mapping data.

An empty mapper indicates no transformations occurred, so position translation is an identity operation.

Returns

true if there are no segments and no generated regions.

pub fn original_to_expanded(&self, pos: u32) -> u32

Converts a position in the original source to the corresponding position in expanded source.

Uses binary search for O(log n) lookup performance.

Arguments

• pos - Byte offset in the original source

Returns

The corresponding byte offset in the expanded source. If the position falls in a gap between segments, returns the position unchanged. If after the last segment, extrapolates based on the delta.

Algorithm

1. Binary search to find the segment containing or after pos
2. If inside a segment, compute offset within segment and translate
3. If after all segments, extrapolate from the last segment
4. Otherwise, return position unchanged (gap or before first segment)

pub fn expanded_to_original(&self, pos: u32) -> Option<u32>

Converts a position in the expanded source back to the original source position.

Returns None if the position is inside macro-generated code that has no corresponding location in the original source.

Arguments

• pos - Byte offset in the expanded source

Returns

Some(original_pos) if the position maps to original code, None if the position is in macro-generated code.

pub fn generated_by(&self, pos: u32) -> Option<String>

Returns the name of the macro that generated code at the given position.

Arguments

• pos - Byte offset in the expanded source

Returns

Some(macro_name) if the position is inside generated code (e.g., “Debug”), None if the position is in original (non-generated) code.

pub fn map_span_to_original( &self, start: u32, length: u32, ) -> Option<SpanResult>

Maps a span (start + length) from expanded source to original source.

Arguments

• start - Start byte offset in expanded source
• length - Length of the span in bytes

Returns

Some(SpanResult) with the mapped span in original source, None if either endpoint is in generated code.

pub fn map_span_to_expanded(&self, start: u32, length: u32) -> SpanResult

Maps a span (start + length) from original source to expanded source.

This always succeeds since every original position has an expanded equivalent.

Arguments

• start - Start byte offset in original source
• length - Length of the span in bytes

Returns

A SpanResult with the mapped span in expanded source.

pub fn is_in_generated(&self, pos: u32) -> bool

Checks if a position is inside macro-generated code.

Arguments

• pos - Byte offset in the expanded source

Returns

true if the position is inside a generated region, false otherwise.

Trait Implementations

impl FromNapiMutRef for NativePositionMapper

unsafe fn from_napi_mut_ref( env: napi_env, napi_val: napi_value, ) -> Result<&'static mut Self>

Safety

impl FromNapiRef for NativePositionMapper

unsafe fn from_napi_ref( env: napi_env, napi_val: napi_value, ) -> Result<&'static Self>

Safety

impl JavaScriptClassExt for NativePositionMapper

fn into_instance<'scope>( self, env: &'scope Env, ) -> Result<ClassInstance<'scope, Self>>

fn into_reference(self, env: Env) -> Result<Reference<Self>>

fn instance_of<'env, V: JsValue<'env>>(env: &Env, value: &V) -> Result<bool>

impl ObjectFinalize for NativePositionMapper

fn finalize(self, env: Env) -> Result<(), Error>

impl ToNapiValue for NativePositionMapper

unsafe fn to_napi_value( env: napi_env, val: NativePositionMapper, ) -> Result<napi_value>

Safety

fn into_unknown(self, env: &Env) -> Result<Unknown<'_>, Error>

impl TypeName for &NativePositionMapper

fn type_name() -> &'static str

fn value_type() -> ValueType

impl TypeName for &mut NativePositionMapper

fn type_name() -> &'static str

fn value_type() -> ValueType

impl TypeName for NativePositionMapper

fn type_name() -> &'static str

fn value_type() -> ValueType

impl ValidateNapiValue for &NativePositionMapper

unsafe fn validate(env: napi_env, napi_val: napi_value) -> Result<napi_value>

Safety

impl ValidateNapiValue for &mut NativePositionMapper

unsafe fn validate(env: napi_env, napi_val: napi_value) -> Result<napi_value>

Safety