# monocart-locator

> A lightweight source code position locator for converting between offset and line/column, with built-in line and comment parsing

Latest version **1.0.3** (published 2026-04-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install monocart-locator
pnpm add monocart-locator
yarn add monocart-locator
bun add monocart-locator
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2026-04-11 |
| First published | 2024-03-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 16.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Maintainers | cenfun |
| Keywords | locator, source, position, offset, line, column, comment, parser |

## Links

- npm: https://www.npmjs.com/package/monocart-locator
- Repository: https://github.com/cenfun/monocart-locator
- Homepage: https://github.com/cenfun/monocart-locator#readme
- Issues: https://github.com/cenfun/monocart-locator/issues
- npm.io page: https://npm.io/package/monocart-locator

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.0.3 (latest) — 2026-04-11
- 1.0.2 — 2024-07-03
- 1.0.1 — 2024-07-01
- 1.0.0 — 2024-03-31

## README

# Monocart Locator
[![](https://img.shields.io/npm/v/monocart-locator)](https://www.npmjs.com/package/monocart-locator)
[![](https://badgen.net/npm/dw/monocart-locator)](https://www.npmjs.com/package/monocart-locator)
![](https://img.shields.io/github/license/cenfun/monocart-locator)

> A lightweight source code position locator for converting between offset and line/column, with built-in line and comment parsing. Zero dependencies.

## Features
- Convert between offset and line/column positions
- Parse source code into lines with metadata (length, indent, blank, comment)
- Detect line comments (`//`) and block comments (`/* */`) with template literal (`${}`) support
- O(log n) position lookups via binary search

## Install
```sh
npm i monocart-locator
```

## Usage

### Locator
The main API for source code position conversion.
```js
const { Locator } = require('monocart-locator');
// or
// import { Locator } from 'monocart-locator';

const locator = new Locator(source);

// Convert 1-based line/column to offset
const offset = locator.locationToOffset({ line: 2, column: 5 });

// Convert offset to 1-based location
const loc = locator.offsetToLocation(100);
// { line, column, length, indent, start, end, blank, comment, text }

// Get source substring
const slice = locator.getSlice(0, 10);

// Get line info by 1-based line number
const lineInfo = locator.getLine(1);

// Access all parsed lines and comments
console.log(locator.lines);     // LineItem[]
console.log(locator.comments);  // CommentItem[]
```

### LineParser
Parse source code into lines with metadata.
```js
const { LineParser } = require('monocart-locator');

const lineParser = new LineParser(source);

console.log(lineParser.lines);     // LineItem[]
console.log(lineParser.comments);  // CommentItem[]

// Find line by offset
const lineInfo = lineParser.findLine(100);
```

### CommentParser
Detect all line and block comments in source code.
```js
const { CommentParser } = require('monocart-locator');

const commentParser = new CommentParser(source);

console.log(commentParser.comments);  // CommentItem[]

// Check if a range is inside a comment
const isComment = commentParser.isComment(start, end);
```

## API

### `Locator`
| Property / Method | Description |
|---|---|
| `source` | Original source string |
| `lines` | `LineItem[]` - all parsed lines |
| `comments` | `CommentItem[]` - all parsed comments |
| `locationToOffset({ line, column })` | Convert 1-based line and column to offset |
| `offsetToLocation(offset)` | Convert offset to `LocationItem` (1-based line and column) |
| `getSlice(start, end)` | Get source substring by offsets |
| `getLine(line)` | Get `LineItem` by 1-based line number |

### `LineItem`
| Property | Type | Description |
|---|---|---|
| `line` | `number` | 0-based line number |
| `length` | `number` | Line length (excluding newline) |
| `indent` | `number` | Leading whitespace count |
| `start` | `number` | Start offset in source |
| `end` | `number` | End offset in source |
| `blank` | `boolean` | Whether line has no non-whitespace content |
| `comment` | `boolean` | Whether first non-whitespace is inside a comment |
| `text` | `string` | Line text (excluding newline) |

### `LocationItem`
Returned by `offsetToLocation()`. Extends `LineItem` with 1-based position:
| Property | Type | Description |
|---|---|---|
| `line` | `number` | 1-based line number |
| `column` | `number` | 0-based column offset |

### `CommentItem`
| Property | Type | Description |
|---|---|---|
| `block` | `boolean` | `true` for block comments (`/* */`), `false` for line comments (`//`) |
| `start` | `number` | Start offset in source |
| `end` | `number` | End offset in source |
| `text` | `string` | Comment text including delimiters |

## License
MIT

---
_Source: https://npm.io/package/monocart-locator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._