iala-light-parser

Parses IALA maritime light characteristic strings into structured ASTs with computed phase sequences.

"Fl(2) W 10s"  →  { type: "Fl", groups: [{count:2}], colors: ["W"], period: 10, sequence: [...] }

The only IALA light characteristic parser on npm. Used by Lighthouse Explorer to animate 18 000 real navigational lights.

Install

npm install iala-light-parser

Usage

import { parse, getState, sampleTimeline, describe } from "iala-light-parser";

// Parse a characteristic string
const c = parse("Fl(2) W 10s");
// → {
//     type: "Fl",
//     groups: [{ count: 2 }],
//     colors: ["W"],
//     period: 10,
//     sequence: [
//       { on: true,  duration: 0.3 },
//       { on: false, duration: 0.3 },
//       { on: true,  duration: 0.3 },
//       { on: false, duration: 9.1 },
//     ]
//   }

// Get current state at a given UTC timestamp (seconds)
const state = getState(c, Date.now() / 1000);
// → { intensity: 0, phaseIndex: 3, phaseProgress: 0.42, color: "W" }

// Human-readable description
describe(c);
// → "2 white flashes, period 10 s"

// Sample timeline for rendering an oscillogram (200 points across one period)
const samples = sampleTimeline(c, 200);
// → [{ time: 0, intensity: 1, color: "W" }, { time: 0.05, intensity: 1, ... }, ...]

Supported types

| Type | Description | Example | |---|---|---| | Fl | Flashing (single or grouped) | Fl W 10s, Fl(3) R 15s | | Fl(m+n) | Composite group flashing | Fl(2+3) W 20s | | LFl | Long flashing (≥ 2s) | LFl W 10s | | Oc | Occulting | Oc W 4s, Oc(3) G 12s | | Iso | Isophase (equal on/off) | Iso W 4s | | Q | Quick (~60/min) | Q W | | Q(n)+LFl | Composite quick + long flash | Q(6)+LFl 15s | | VQ | Very quick (~120/min) | VQ(9)+LFl 10s | | UQ | Ultra quick (~240/min) | UQ W | | IQ / IVQ / IUQ | Interrupted quick | IQ 10s | | Mo | Morse code | Mo(A) W 8s | | Al | Alternating | Al.WR 8s | | F | Fixed | F W |

API

parse(input: string): LightCharacteristic

Parses an IALA characteristic string. Throws ParseError on invalid input.

getState(characteristic, timestampSeconds): LightState

Pure deterministic function — same input always produces same output. No internal state.

interface LightState {
  intensity: number;      // 0 = off, 1 = on
  phaseIndex: number;     // current phase in sequence
  phaseProgress: number;  // [0, 1] progress within current phase
  color: LightColor;      // "W" | "R" | "G" | "Y" | "Bu" | "Vi"
}

describe(characteristic, overrideColor?): string

Returns a plain-English description. Pass overrideColor to override the color from the characteristic string (useful for sector lights where the color comes from a separate tag).

sampleTimeline(characteristic, sampleCount?): TimelineSnapshot[]

Samples the light state at evenly-spaced intervals across one full period. Useful for rendering oscillograms and timeline visualizations.

Design

All functions are pure and stateless — no new Engine(), no start(), no internal timers. Feed in a timestamp, get back a state. This makes the library trivial to test and use in any environment: browser, Node, CLI, Three.js, React Native.

// Works in any context
const state = getState(parse("Fl W 10s"), 1234567890.5);

License

MIT