# wmap-parser-js

A pure-javascript parser for `wmap` formatted Wardley Map files.

## Features

* No dependencies.
* Pure JavaScript, browser and runtime friendly.
* Free software.
* Reasonably fast.

## Installation

Install with your favorite package manager.

```bash
pnpm add wmap-parser
```

```bash
yarn add wmap-parser
```

```bash
npm install wmap-parser
```

## Usage

```javascript
import { parse } from "wmap-parser";

const wmapSource = `
[I] 0.25
[II] 0.5
[III] 0.75
[IV] 1.0

Tea (0.9, 0.5) [Circle]
Cup (0.8, 0.4)
Hot Water (0.6, 0.2)

Tea -> Cup
Cup -> Hot Water

[Note] (0.5, 0.5) Supply chain for tea
[Group] Tea, Cup
[Inertia] Cup
[Evolution] Tea + 0.1
`;

const map = parse(wmapSource);

console.log(map.components);
// [
//   { label: 'Tea', coordinates: [0.9, 0.5], shape: 'circle' },
//   { label: 'Cup', coordinates: [0.8, 0.4], shape: 'circle' },
//   ...
// ]

console.log(map.dependencies);
// [
//   { from: 'Tea', to: 'Cup', isDirected: true },
//   ...
// ]
```

## API

### `parse(source: string): Map`

Parses a wmap formatted string and returns a Map object.

**Parameters:**

- `source` (string): The wmap source code to parse

**Returns:**

- `Promise<Map>`: A promise that resolves to a Map object

For mor comprehensive type definitions, check the JSDoc comments inside.

## Format Specification

See [The map website](https://map.tranquil.systems) for more information on the
format.

## Reasonably Fast

Benchmarked on an M1 Pro mac. A map with around 120 entities parses in 16µs.
While a larger map with slightly under 2000 entities does so in 447µs.

You can run the benchmarks by using:

```bash
make benchmark
```

## Development

This project uses a Makefile to run all commands. This is to keep the
commands uniform with the other wmap-parser projects.

### Running Tests

```bash
make test
```

Or to see coverage

```bash
make coverage
```

## See Also

- [wmap specification](doc/wmap-spec.ebnf) - Formal grammar
- [wmap specification](https://git.sr.ht:~rbdr/wmap-parser-rust) - Rust wmap-parser
- [wmap specification](https://git.sr.ht:~rbdr/wmap-parser-c) - ANSI C wmap-parser
- [wmap specification](https://git.sr.ht:~rbdr/wmap-parser-swift) - Swift wmap-parser
- [Wardley Maps](https://wardleymaps.com/) - Learn about Wardley Mapping