Improve docs, and match API of other parsers

1 files changed, 41 insertions, 198 deletions

diff --git a/README.md b/README.md
index 1d90963..1ca023c 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,28 @@
-# wmap-parser
+# wmap-parser-js
 
-A high-performance JavaScript parser for wmap formatted Wardley Map files.
+A pure-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
+* No dependencies.
+* Pure JavaScript, browser and runtime friendly.
+* Free software.
+* Reasonably fast.
 
 ## Installation
 
+Install with your favorite package manager.
+
 ```bash
-npm install wmap-parser
+pnpm add wmap-parser
 ```
 
-Or with pnpm:
+```bash
+yarn add wmap-parser
+```
 
 ```bash
-pnpm add wmap-parser
+npm install wmap-parser
 ```
 
 ## Usage
@@ -46,21 +49,25 @@ Cup -> Hot Water
 [Evolution] Tea + 0.1
 `;
 
-const map = await parse(wmapSource);
+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.entities);
+console.log(map.dependencies);
 // [
-//   { 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 },
+//   { from: 'Tea', to: 'Cup', isDirected: true },
 //   ...
 // ]
 ```
 
 ## API
 
-### `parse(source: string): Promise<Map>`
+### `parse(source: string): Map`
 
 Parses a wmap formatted string and returns a Map object.
 
@@ -72,209 +79,45 @@ Parses a wmap formatted string and returns a Map object.
 
 - `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;
-}
-```
+For mor comprehensive type definitions, check the JSDoc comments inside.
 
 ## Format Specification
 
-The wmap format supports the following entity types:
-
-### Components (Vertices)
+See [The map website](https://map.tranquil.systems) for more information on the
+format.
 
-```
-ComponentName (x, y)
-ComponentName (x, y) [Shape]
-```
-
-- Coordinates are decimal numbers (0-100 range typical)
-- Optional shape: `x`, `Square`, `Triangle`, or `Circle` (case-insensitive)
+## Reasonably Fast
 
-### Dependencies (Edges)
+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.
 
-```
-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:
+You can run the benchmarks by using:
 
 ```bash
-npm run benchmark
+make 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
 
+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
-npm test
+make test
 ```
 
-Tests use Node's built-in test runner (`node:test`) with no external dependencies.
-
-### Running Benchmarks
+Or to see coverage
 
 ```bash
-npm run benchmark
+make coverage
 ```
 
-## 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
+- [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