sor-reader

Zero-dependency TypeScript parser for OTDR SOR files (Standard OTDR Record, Bellcore/Telcordia SR-4731 v1.x and v2.x).

Works in Node.js ≥ 18 and modern browsers (via Uint8Array — no Buffer required).

Features

• Full SOR v1 and v2 support
• Parses all standard blocks: MapBlock, GenParams, SupParams, FxdParams, KeyEvents, DataPts, Cksum
• CRC16-CCITT checksum verification
• Trace data export as tab-separated .dat (identical to pyOTDR output)
• JSON output matching pyOTDR (sorted keys, 8-space indent)
• Browser-safe entry point (sor-reader/browser) — no Node.js APIs in the core
• CLI tool for quick file processing
• Full TypeScript types and JSDoc

Installation

npm install sor-reader

Quick Start

Node.js

import { parseSorFile, toJSON, traceToString } from "sor-reader";

const result = await parseSorFile("measurement.sor");

console.log(`Format: v${result.format}`);
console.log(`Data points: ${result.FxdParams["num data points"]}`);
console.log(`Wavelength: ${result.FxdParams.wavelength}`);
console.log(`Checksum OK: ${result.Cksum.match}`);

// Write pyOTDR-compatible JSON
import { writeFileSync } from "fs";
writeFileSync("measurement-dump.json", toJSON(result));

// Write trace data
writeFileSync("measurement-trace.dat", traceToString(result.trace));

Browser / Bundler

import { parseSor, toJSON, traceToString } from "sor-reader/browser";

// From a file input or fetch response
const response = await fetch("measurement.sor");
const buffer = await response.arrayBuffer();
const data = new Uint8Array(buffer);

const result = parseSor(data, "measurement.sor");
console.log(toJSON(result));

CommonJS

const { parseSorFile, toJSON } = require("sor-reader");

CLI

# Parse a single file (writes measurement-dump.json + measurement-trace.dat)
npx sor-reader measurement.sor

# Multiple files
npx sor-reader *.sor

# Print JSON to stdout only
npx sor-reader --stdout --no-trace measurement.sor

# Skip JSON output
npx sor-reader --no-json measurement.sor

CLI Options

| Option | Description | |---|---| | --json / --no-json | Write JSON dump (default: enabled) | | --trace / --no-trace | Write trace .dat file (default: enabled) | | --stdout | Print JSON to stdout instead of file | | --help, -h | Show help | | --version, -v | Print version |

API Reference

parseSor(data, filename?, options?)

Parse a SOR file from a Uint8Array.

function parseSor(
  data: Uint8Array,
  filename?: string,
  options?: ParseOptions,
): SorResult

parseSorFile(filepath, options?) (Node.js only)

Parse a SOR file from a filesystem path.

async function parseSorFile(
  filepath: string,
  options?: ParseOptions,
): Promise<SorResult>

toJSON(result)

Serialize a SorResult to a JSON string compatible with pyOTDR output (sorted keys, 8-space indent).

function toJSON(result: SorResult): string

traceToString(trace)

Convert trace data to a tab-separated string (distance\tpower\n per line).

function traceToString(trace: TracePoint[]): string

SorResult Structure

interface SorResult {
  filename: string;
  format: 1 | 2;           // SOR version
  version: string;          // e.g. "2.00"
  mapblock: MapBlockInfo;
  blocks: Record<string, BlockInfo>;
  GenParams: GenParamsRaw;  // General parameters
  SupParams: SupParamsRaw;  // Supplier parameters
  FxdParams: FxdParamsRaw;  // Fixed parameters (wavelength, range, etc.)
  KeyEvents: KeyEventsRaw;  // Detected events and summary
  DataPts: DataPtsRaw;      // Trace metadata
  Cksum: CksumRaw;          // Checksum verification
  trace: TracePoint[];      // [{distance, power}, ...] in km / dB
}

Key fields

| Field | Type | Description | |---|---|---| | FxdParams["wavelength"] | string | e.g. "1310 nm" | | FxdParams["num data points"] | number | Number of trace samples | | FxdParams["range"] | number | Measurement range in km | | FxdParams["resolution"] | number | Sample resolution in m | | FxdParams["index"] | number | Group index of refraction | | FxdParams["date/time"] | string | Human-readable timestamp | | KeyEvents["num events"] | number | Number of detected events | | Cksum.match | boolean | Whether checksum is valid | | trace[i].distance | number | Distance in km | | trace[i].power | number | Signal level in dB |

Compatibility

| Environment | Support | |---|---| | Node.js ≥ 18 | Full (including parseSorFile) | | Node.js 16 | Core parseSor only (no parseArgs for CLI) | | Browsers (modern) | sor-reader/browser entry — all features except parseSorFile | | Deno | Use parseSor with Uint8Array from Deno.readFile | | Bun | Full support |

Comparison with pyOTDR

| Feature | pyOTDR (Python) | sor-reader (TS) | |---|---|---| | SOR v1 | ✅ | ✅ | | SOR v2 | ✅ | ✅ | | CRC16 checksum | ✅ | ✅ | | Trace output | ✅ | ✅ (byte-identical) | | JSON output | ✅ | ✅ (byte-identical) | | Browser support | ❌ | ✅ | | TypeScript types | ❌ | ✅ | | Zero dependencies | ❌ (crc pkg) | ✅ | | CLI | ✅ | ✅ |

SOR File Format

SOR files follow the Bellcore/Telcordia SR-4731 standard for OTDR (Optical Time-Domain Reflectometer) measurements. The format stores:

• General parameters: fiber type, cable ID, operator, location
• Supplier parameters: OTDR make/model, firmware version
• Fixed parameters: wavelength, pulse width, measurement range, IOR
• Key events: detected splices, reflections, and end-of-fiber
• Data points: raw backscatter trace samples
• Checksum: CRC16-CCITT over all preceding bytes

License

MIT — see LICENSE.

Ported from pyOTDR (GPL-3.0) by Sidney Li. The port is a clean-room reimplementation in TypeScript, licensed under MIT.