path: root/README.md

# wmap-parser

A high-performance JavaScript parser for wmap formatted Wardley Map files.

## Features

- **Zero dependencies** (dev dependencies only for testing and benchmarking)
- **High performance** state machine parser
- **TypeScript-friendly** with comprehensive JSDoc type definitions
- **Cross-platform** line ending support (LF, CRLF, CR)
- **Robust** error handling - invalid lines are gracefully ignored

## Installation

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

Or with pnpm:

```bash
pnpm add 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 = await parse(wmapSource);

console.log(map.entities);
// [
//   { type: 'stage', number: 'i', value: 0.25 },
//   { type: 'stage', number: 'ii', value: 0.5 },
//   { type: 'component', label: 'Tea', coordinates: [0.9, 0.5], shape: 'circle' },
//   { type: 'dependency', from: 'Tea', to: 'Cup', isDirected: true },
//   ...
// ]
```

## API

### `parse(source: string): Promise<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

### Type Definitions

#### Map

```typescript
{
  entities: Entity[]
}
```

#### Entity

Union type of: `Component | Dependency | Note | Stage | Group | Inertia | Evolution`

#### Component

```typescript
{
  type: "component";
  label: string;
  coordinates: [number, number];
  shape: string | null; // 'x' | 'square' | 'triangle' | 'circle' | null
}
```

#### Dependency

```typescript
{
  type: "dependency";
  from: string;
  to: string;
  isDirected: boolean; // true for ->, false for --
}
```

#### Note

```typescript
{
  type: "note";
  coordinates: [number, number];
  text: string;
}
```

#### Stage

```typescript
{
  type: "stage";
  number: string; // 'i' | 'ii' | 'iii' | 'iv'
  value: number;
}
```

#### Group

```typescript
{
  type: 'group'
  vertices: string[]
}
```

#### Inertia

```typescript
{
  type: "inertia";
  vertex: string;
}
```

#### Evolution

```typescript
{
  type: "evolution";
  vertex: string;
  isPositive: boolean;
  value: number;
}
```

## Format Specification

The wmap format supports the following entity types:

### Components (Vertices)

```
ComponentName (x, y)
ComponentName (x, y) [Shape]
```

- Coordinates are decimal numbers (0-100 range typical)
- Optional shape: `x`, `Square`, `Triangle`, or `Circle` (case-insensitive)

### Dependencies (Edges)

```
Source -> Target  # Directed dependency
Source -- Target  # Undirected dependency
```

### Notes

```
[Note] (x, y) Note text content
```

### Stages

```
[I] 0.25
[II] 0.5
[III] 0.75
[IV] 1.0
```

- Stage numbers: `I`, `II`, `III`, or `IV` (case-insensitive)

### Groups

```
[Group] Component1, Component2, Component3
```

### Inertia

```
[Inertia] ComponentName
```

### Evolution

```
[Evolution] ComponentName + 0.5
[Evolution] ComponentName - 0.3
```

See the [formal EBNF specification](doc/wmap-spec.ebnf) for complete grammar details.

## Performance

The parser uses a character-by-character state machine approach for optimal performance:

- **No regex overhead** - direct character comparisons
- **Minimal allocations** - efficient string operations
- **Single-pass parsing** - each line processed once
- **Cache-friendly** - sequential memory access

Benchmark on a typical map with ~120 entities:

- **~50,000+ operations/second**
- **~0.02ms average parse time**

Run benchmarks yourself:

```bash
npm run benchmark
```

## Error Handling

The parser is designed to be fault-tolerant:

- Invalid lines are silently ignored
- Partial entities are not added to the result
- Empty lines and whitespace are handled gracefully
- Different line endings (LF, CRLF, CR) are all supported

## Development

### Running Tests

```bash
npm test
```

Tests use Node's built-in test runner (`node:test`) with no external dependencies.

### Running Benchmarks

```bash
npm run benchmark
```

## License

AGPL-v3

## Contributing

This is a focused, performance-oriented parser. Contributions should maintain:

- Zero runtime dependencies
- High performance characteristics
- Simple, readable code
- Comprehensive test coverage

## See Also

- [wmap specification](doc/wmap-spec.ebnf) - Formal grammar
- [Wardley Maps](https://wardleymaps.com/) - Learn about Wardley Mapping