swimparse 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Goergen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# swimparse
+
+Reads swim-meet result files — **SDIF v3** (`.sd3`) and **Hy-Tek** (`.hy3`) — and emits
+one `NormalizedMeet` JSON shape, so tools consume a single contract instead of
+re-implementing fixed-width parsing twice.
+
+- **Zero dependencies.** Plain ESM — browser, Node, and CI unchanged.
+- **Lossless.** Every swim is kept: placing or not, exhibition, DQ, no-show — plus
+  birthdates, seed times, relay legs, splits and DQ reasons.
+- **Format-agnostic output.** SDIF and HY3 of the same meet parse to the same result.
+
+## Scope
+
+swimparse reads files and emits JSON. **That is all it does.** It has no concept of a
+league: no age bands, no scoring rules, no team-code registry, no qualifying standards,
+no synthesized meet names.
+
+That boundary is deliberate. Those things differ per league and change over time, while
+the file formats do not. Keeping them out means a summer-league scorer, a USA-Swimming
+analyzer, and a championship-meet tool can share one parser and disagree about
+everything else.
+
+| Concern | Where it belongs |
+|---|---|
+| SDIF / HY3 record layouts, times, dates, format detection | **swimparse** |
+| The `NormalizedMeet` contract | **swimparse** |
+| Age bands, age-up date, age-group labels for swimmers | your league layer |
+| Scoring: point values, which relays count, team totals | your league layer |
+| Canonical team codes / alias mapping | your league layer |
+| Stripping or aggregating PII | your league layer |
+| Qualifying standards, records, personal bests | your application |
+
+## Install
+
+Consumed as a pinned git dependency:
+
+```json
+"dependencies": { "swimparse": "github:g0rgonus/swimparse#v0.1.0" }
+```
+
+Pin to a tag or SHA for reproducibility. `npm ci` clones it in CI with no publish step.
+
+## Usage
+
+```js
+import { parse, detectFormat } from 'swimparse';
+
+const meet = parse(fileText, { filename: 'GG_at_WW.hy3' }); // auto-detects format
+const meet = parse(fileText, { format: 'sdif-v3' });        // or force one
+```
+
+CLI:
+
+```bash
+swimparse meet.hy3 --pretty       # NormalizedMeet JSON to stdout
+swimparse meet.sd3 -o meet.json   # to a file
+swimparse a.sd3 b.hy3 -d out/     # one <name>.json per input
+```
+
+## The NormalizedMeet contract
+
+`{ format, source, meet, teams, swimmers, events }` — see [`src/model.js`](src/model.js)
+for the full typedefs. Highlights:
+
+- **Times** always carry both `{ text: "1:11.35", seconds: 71.35 }`.
+- **Dates** are ISO `YYYY-MM-DD`.
+- **`result.status`** is `ok | dq | ns | dnf | scratch | exhibition`.
+- **`event.ageGroup`** is the *event's* age range as printed in the file (`"9-10"`,
+  `"10 & Under"`, `"Open"`). It is **not** a swimmer's age group — computing that needs
+  a birthdate and a league's bands, which is your layer's job.
+- **`team.code`** has the two-letter LSC prefix stripped (`VAWW` → `WW`), an SDIF file
+  convention; `team.fullCode` keeps the raw value. Mapping either onto a league's
+  canonical code is your layer's job.
+- **`result.points`** is whatever the file stored. SDIF carries points; HY3 does not, so
+  it reads `0`. Deriving points from place is scoring, so it lives in your layer.
+
+### Format differences worth knowing
+
+| | SDIF (`.sd3`) | Hy-Tek (`.hy3`) |
+|---|---|---|
+| DQ time | nulled | **retained** (`finalTime` kept) |
+| DQ reason | — | **`dqReason`** (e.g. "Arms: Underwater recovery") |
+| Points | stored | absent (reads `0`) |
+| Names | 28-char field | wider, less truncation |
+
+## Privacy
+
+The lossless rule means output carries **`swimmers[].birthDate` and `usasId` whenever the
+file does.** At a youth meet that is PII for minors, so **treat every parse result as
+confidential** until your application has stripped or aggregated it.
+
+swimparse does not sanitize for you, on purpose: what counts as safe is a league decision
+(a summer league publishes age-group labels and drops birthdates; a USA-Swimming tool
+needs exact ages). Putting that choice in the parser would force one answer on everyone.
+
+Test fixtures in this repo are synthetic — every identity is a public figure with a
+shifted birth year; see [`test/fixtures/README.md`](test/fixtures/README.md).
+
+## Tests
+
+```bash
+node --test    # golden snapshots + SDIF↔HY3 cross-agreement
+```
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * swimparse CLI — turn .sd3/.hy3 files into NormalizedMeet JSON.
+ *
+ *   swimparse meet.hy3                     # JSON to stdout
+ *   swimparse meet.sd3 -o meet.json        # JSON to a file
+ *   swimparse a.sd3 b.hy3 -d out/          # one <name>.json per input, into out/
+ *   swimparse meet.hy3 --pretty            # 2-space indented
+ *
+ * PRIVACY: the output contains swimmer birthdates and registration ids exactly
+ * as the source file carries them. For a youth meet that is PII for minors —
+ * do not publish it or commit it to a public repo without sanitizing first.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, join, extname } from 'node:path';
+import { parse } from './src/index.js';
+
+function main(argv) {
+    const args = argv.slice(2);
+    const inputs = [];
+    let outFile = null;
+    let outDir = null;
+    let pretty = false;
+
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '-o' || a === '--out') outFile = args[++i];
+        else if (a === '-d' || a === '--out-dir') outDir = args[++i];
+        else if (a === '--pretty') pretty = true;
+        else if (a === '-h' || a === '--help') return help(0);
+        else if (a.startsWith('-')) return fail(`unknown option: ${a}`);
+        else inputs.push(a);
+    }
+    if (inputs.length === 0) return help(1);
+    if (outFile && inputs.length > 1) return fail('-o takes a single input; use -d for multiple');
+
+    const indent = pretty ? 2 : 0;
+    if (outDir) mkdirSync(outDir, { recursive: true });
+
+    for (const file of inputs) {
+        const meet = parse(readFileSync(file, 'latin1'), { filename: file });
+        const json = JSON.stringify(meet, null, indent);
+        if (outDir) {
+            const name = basename(file, extname(file)) + '.json';
+            writeFileSync(join(outDir, name), json);
+            process.stderr.write(`wrote ${join(outDir, name)} (${meet.format}, ${meet.events.length} events)\n`);
+        } else if (outFile) {
+            writeFileSync(outFile, json);
+            process.stderr.write(`wrote ${outFile} (${meet.format}, ${meet.events.length} events)\n`);
+        } else {
+            process.stdout.write(json + '\n');
+        }
+    }
+    return 0;
+}
+
+function help(codeNum) {
+    process.stdout.write(
+        'Usage: swimparse <file...> [-o out.json | -d out-dir] [--pretty]\n' +
+        '  Parses SDIF (.sd3) or Hy-Tek (.hy3) results into NormalizedMeet JSON.\n' +
+        '  -o, --out <path>      write a single input to this file\n' +
+        '  -d, --out-dir <dir>   write one <name>.json per input into this directory\n' +
+        '      --pretty          2-space indented JSON\n' +
+        '\n' +
+        '  Output carries swimmer birthdates as they appear in the file. Sanitize\n' +
+        '  before publishing. Age banding, scoring, and team-code mapping are league\n' +
+        '  policy and are not performed here.\n'
+    );
+    return codeNum;
+}
+function fail(msg) {
+    process.stderr.write(`swimparse: ${msg}\n`);
+    return 2;
+}
+
+// Set exitCode rather than process.exit(): process.exit() can terminate before
+// a large stdout write drains to a pipe, truncating JSON at ~64KB (fine to a TTY
+// or file, broken when a parent process captures stdout). Letting the event loop
+// empty naturally flushes the write first.
+process.exitCode = main(process.argv);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "swimparse",
+  "version": "0.1.0",
+  "description": "Parses SDIF v3 (.sd3) and Hy-Tek (.hy3) swim-meet result files into one NormalizedMeet JSON contract. Zero dependencies; runs in the browser, Node, and CI.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./sdif": "./src/sdif.js",
+    "./hy3": "./src/hy3.js"
+  },
+  "bin": {
+    "swimparse": "cli.js"
+  },
+  "files": [
+    "src/",
+    "cli.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/g0rgonus/swimparse.git"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "swimming",
+    "sdif",
+    "sd3",
+    "hy3",
+    "hy-tek",
+    "meet-results",
+    "parser",
+    "swim-meet"
+  ]
+}

package/src/constants.js

@@ -0,0 +1,87 @@
+/**
+ * Shared vocabulary for meet-result parsing.
+ *
+ * Both the SDIF and HY3 adapters map their raw codes onto these canonical
+ * values so that a NormalizedMeet looks identical regardless of source format.
+ */
+
+/** Canonical stroke names. */
+export const STROKE = {
+    FREESTYLE: 'Freestyle',
+    BACKSTROKE: 'Backstroke',
+    BREASTSTROKE: 'Breaststroke',
+    BUTTERFLY: 'Butterfly',
+    IM: 'IM',
+    MEDLEY: 'Medley', // medley relay
+};
+
+/** SDIF numeric stroke codes → canonical stroke. */
+export const SDIF_STROKE = {
+    '1': STROKE.FREESTYLE,
+    '2': STROKE.BACKSTROKE,
+    '3': STROKE.BREASTSTROKE,
+    '4': STROKE.BUTTERFLY,
+    '5': STROKE.IM,
+    '6': STROKE.FREESTYLE, // free relay
+    '7': STROKE.MEDLEY,    // medley relay
+};
+
+/** HY3 letter stroke codes → canonical stroke. */
+export const HY3_STROKE = {
+    A: STROKE.FREESTYLE,
+    B: STROKE.BACKSTROKE,
+    C: STROKE.BREASTSTROKE,
+    D: STROKE.BUTTERFLY,
+    E: STROKE.IM,
+    // F/G are diving events
+};
+
+/** Raw single-char sex/gender code → canonical. */
+export const GENDER = { M: 'M', F: 'F', X: 'X' };
+
+/** Human display for a gender code, in event context. */
+export const GENDER_DISPLAY = { M: 'Boys', F: 'Girls', X: 'Mixed' };
+
+/** Course codes → canonical course. */
+export const COURSE = { Y: 'SCY', L: 'LCM', S: 'SCM' };
+
+/**
+ * Result status. A swim that "counts" is `ok`; everything else is excluded
+ * from scoring, but all of them are recorded — consumers filter.
+ * @typedef {'ok'|'dq'|'ns'|'dnf'|'scratch'|'exhibition'} ResultStatus
+ */
+
+/**
+ * Parses a 4-char SDIF/HY3-style age code into a labelled age group.
+ * Examples: "0910" → 9-10, "UN10" → 10 & Under, "UNOV" → Open.
+ *
+ * @param {string} lowerStr - 2-char lower bound ("09", "UN", "15", ...)
+ * @param {string} upperStr - 2-char upper bound ("10", "OV", "18", ...)
+ * @returns {{ label: string, lower: number, upper: number }}
+ */
+export function ageGroup(lowerStr, upperStr) {
+    const lo = (lowerStr || '').trim();
+    const hi = (upperStr || '').trim();
+
+    if ((lo === 'UN' || lo === '0' || lo === '') && (hi === 'OV' || hi === '109' || hi === '')) {
+        return { label: 'Open', lower: 0, upper: 99 };
+    }
+    if (lo === 'UN' || lo === '0' || lo === '') {
+        const upper = parseInt(hi, 10);
+        return Number.isNaN(upper)
+            ? { label: 'Open', lower: 0, upper: 99 }
+            : { label: `${upper} & Under`, lower: 0, upper };
+    }
+    if (hi === 'OV' || hi === '109') {
+        const lower = parseInt(lo, 10);
+        return Number.isNaN(lower)
+            ? { label: 'Open', lower: 0, upper: 99 }
+            : { label: `${lower} & Over`, lower, upper: 99 };
+    }
+    const lower = parseInt(lo, 10);
+    const upper = parseInt(hi, 10);
+    if (Number.isNaN(lower) || Number.isNaN(upper)) {
+        return { label: 'Open', lower: 0, upper: 99 };
+    }
+    return { label: lower === upper ? `${lower}` : `${lower}-${upper}`, lower, upper };
+}

package/src/detect.js

@@ -0,0 +1,29 @@
+/**
+ * Format detection. Prefers content sniffing over file extension, since both
+ * formats are plain text and extensions are sometimes wrong.
+ */
+
+/**
+ * @param {string} content
+ * @param {string} [filename] optional, used only as a tie-breaker
+ * @returns {'sdif-v3'|'hy3'|null}
+ */
+export function detectFormat(content, filename) {
+    const firstLines = String(content).split(/\r?\n/, 5);
+    for (const line of firstLines) {
+        const code = line.slice(0, 2);
+        // HY3 files open with an A1 file-description record.
+        if (code === 'A1') return 'hy3';
+        // SDIF v3 files open with an A0 file record (or at least carry B1).
+        if (code === 'A0' || code === 'B1') return 'sdif-v3';
+    }
+    if (firstLines.some((l) => l.startsWith('B11') || l.startsWith('D0') || l.startsWith('D3'))) return 'sdif-v3';
+    if (firstLines.some((l) => l.startsWith('D1') || l.startsWith('E1'))) return 'hy3';
+
+    if (filename) {
+        const ext = filename.toLowerCase().split('.').pop();
+        if (ext === 'hy3') return 'hy3';
+        if (ext === 'sd3' || ext === 'cl2' || ext === 'txt') return 'sdif-v3';
+    }
+    return null;
+}

package/src/hy3.js

@@ -0,0 +1,242 @@
+/**
+ * Hy-Tek (.hy3) adapter → NormalizedMeet.
+ *
+ * 130-char fixed-width records (128 data + 2 checksum), CP-1252, CRLF.
+ * Record types handled:
+ *   A1 file · B1 meet · C1 team · D1 athlete
+ *   E1 entry / E2 result (individual, paired)
+ *   F1 entry / F2 result / F3 legs (relay)
+ *   G1 splits · H1 DQ reason
+ *
+ * Two things HY3 gives us that SDIF does not: it RETAINS the swum time on a DQ,
+ * and it carries a structured DQ reason (H1). One thing it lacks: meet
+ * points — Hy-Tek computes standings separately — so result.points is 0 here and
+ * must be derived by a consumer from place + league scoring rules.
+ *
+ * Offsets for D1/E1/E2/F3 were verified empirically against a real GG-at-WW file.
+ */
+
+import { HY3_STROKE, STROKE, GENDER_DISPLAY, ageGroup } from './constants.js';
+import { timeFromSeconds, normalizeDate } from './times.js';
+import { displayTeamCode, deriveSwimmers } from './model.js';
+
+const slice = (line, a, b) => (line.length >= a ? line.slice(a, b).trim() : '');
+const num = (s) => {
+    const v = parseFloat(s);
+    return Number.isNaN(v) || v <= 0 ? null : v;
+};
+
+// "Last, First M" — append the middle initial when present, matching how SDIF
+// packs its D0 name field so the two formats produce identical display names.
+const athleteName = (a) => {
+    if (!a) return '';
+    const base = a.first ? `${a.last}, ${a.first}` : a.last;
+    return a.middle ? `${base} ${a.middle}` : base;
+};
+
+// Event-sex code (W/M/G/B/X) → canonical gender.
+const EVENT_SEX = { M: 'M', B: 'M', W: 'F', G: 'F', F: 'F', X: 'X' };
+
+// E2/F2 status char → canonical ResultStatus.
+const STATUS = { ' ': 'ok', '': 'ok', Q: 'dq', F: 'ns', R: 'scratch', D: 'dnf', S: 'exhibition' };
+
+// On a RELAY, HY3 reuses the stroke letters differently: A = Freestyle relay,
+// E = Medley relay (vs individual E = IM). Map relays explicitly.
+const HY3_RELAY_STROKE = { A: STROKE.FREESTYLE, E: STROKE.MEDLEY };
+
+/**
+ * @param {string} content raw .hy3 text
+ * @returns {import('./model.js').NormalizedMeet}
+ */
+export function parseHy3(content) {
+    const lines = String(content).split(/\r?\n/);
+
+    /** @type {import('./model.js').MeetInfo} */
+    const meet = { name: '', rawName: '', startDate: null };
+    const teamMap = new Map();
+    const eventMap = new Map();
+    /** @type {Map<string, {last:string,first:string,gender:string,birthDate:string|null,usasId:string|null}>} */
+    const athletes = new Map();
+    const source = {};
+
+    let currentTeam = null;
+    let currentAthlete = null; // athlete number
+    let lastResult = null;     // most recent individual or relay result (for splits / DQ reason)
+    let lastRelay = null;      // most recent relay (for F3 legs)
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const code = line.slice(0, 2);
+        try {
+            switch (code) {
+                case 'A1':
+                    source.software = slice(line, 44, 58) || undefined;
+                    source.createdAt = normalizeDate(slice(line, 58, 66));
+                    break;
+                case 'B1':
+                    meet.rawName = slice(line, 2, 47);
+                    meet.name = meet.rawName;
+                    meet.startDate = normalizeDate(slice(line, 92, 100));
+                    break;
+                case 'C1': {
+                    const raw = slice(line, 2, 7);
+                    currentTeam = raw;
+                    if (!teamMap.has(raw)) {
+                        teamMap.set(raw, { code: displayTeamCode(raw), fullCode: raw, name: slice(line, 7, 37) });
+                    }
+                    break;
+                }
+                case 'D1': {
+                    const anum = slice(line, 3, 8);
+                    currentAthlete = anum;
+                    athletes.set(anum, {
+                        last: slice(line, 8, 28),
+                        first: slice(line, 28, 48),
+                        preferred: slice(line, 48, 68) || undefined,
+                        middle: slice(line, 68, 69) || undefined,
+                        gender: slice(line, 2, 3),
+                        birthDate: normalizeDate(slice(line, 88, 96)),
+                        usasId: slice(line, 69, 83) || null,
+                        team: currentTeam,
+                    });
+                    break;
+                }
+                case 'E1': {
+                    const e2 = lines[i + 1] && lines[i + 1].slice(0, 2) === 'E2' ? lines[i + 1] : '';
+                    lastResult = parseIndividual(line, e2, eventMap, athletes, currentAthlete, teamMap);
+                    lastRelay = null;
+                    break;
+                }
+                case 'F1': {
+                    const f2 = lines[i + 1] && lines[i + 1].slice(0, 2) === 'F2' ? lines[i + 1] : '';
+                    lastRelay = parseRelay(line, f2, eventMap, currentTeam, teamMap);
+                    lastResult = lastRelay;
+                    break;
+                }
+                case 'F3':
+                    if (lastRelay) parseRelayLegs(line, lastRelay, athletes);
+                    break;
+                case 'H1':
+                    if (lastResult && lastResult.disqualified) {
+                        lastResult.dqCode = slice(line, 2, 4);
+                        lastResult.dqReason = slice(line, 4, 52);
+                    }
+                    break;
+            }
+        } catch {
+            /* skip malformed line */
+        }
+    }
+
+    const events = [...eventMap.values()];
+    for (const ev of events) ev.results.sort((a, b) => (a.place ?? 999) - (b.place ?? 999));
+    const teams = [...teamMap.values()];
+
+    // Enrich the derived registry with athlete-level gender/usasId from D1.
+    const enrich = new Map();
+    for (const a of athletes.values()) {
+        const key = `${a.last}|${a.first}|${a.birthDate || ''}`.toLowerCase();
+        enrich.set(key, {
+            gender: a.gender === 'M' || a.gender === 'F' ? a.gender : undefined,
+            usasId: a.usasId,
+            preferredName: a.preferred,
+        });
+    }
+    const swimmers = deriveSwimmers(events, enrich);
+
+    return { format: 'hy3', source, meet, teams, swimmers, events };
+}
+
+function parseIndividual(e1, e2, eventMap, athletes, anum, teamMap) {
+    const eventNum = slice(e1, 38, 42);
+    const ev = ensureEvent(eventMap, buildEvent(e1, 'individual', { sex: [14, 15], dist: [15, 21], stroke: [21, 22], age: [22, 28] }), eventNum);
+
+    const a = athletes.get(anum) || { last: slice(e1, 8, 13), first: '', birthDate: null, team: null };
+    const swimmerName = athleteName(a);
+    const status = STATUS[e2 ? e2[12] : ' '] || 'ok';
+    const seconds = e2 ? num(e2.slice(4, 11)) : null;
+    const place = e2 ? parseInt(slice(e2, 30, 33), 10) : NaN;
+
+    /** @type {import('./model.js').IndividualResult} */
+    const result = {
+        kind: 'individual',
+        swimmerName,
+        teamCode: teamMap.get(a.team)?.code || a.team || '',
+        birthDate: a.birthDate,
+        seedTime: timeFromSeconds(num(e1.slice(52, 59))),
+        finalTime: timeFromSeconds(seconds), // retained even on DQ (HY3 keeps it)
+        status,
+        disqualified: status === 'dq',
+        place: Number.isNaN(place) ? null : place || null,
+        points: 0, // HY3 stores no points; deriving them is a consumer concern
+    };
+    ev.results.push(result);
+    return result;
+}
+
+function parseRelay(f1, f2, eventMap, currentTeam, teamMap) {
+    const eventNum = slice(f1, 38, 42);
+    const ev = ensureEvent(eventMap, buildEvent(f1, 'relay', { sex: [14, 15], dist: [18, 21], stroke: [21, 22], age: [22, 28] }), eventNum);
+
+    const status = STATUS[f2 ? f2[12] : ' '] || 'ok';
+    const seconds = f2 ? num(f2.slice(5, 11)) : null;
+    const place = f2 ? parseInt(slice(f2, 30, 33), 10) : NaN;
+
+    /** @type {import('./model.js').RelayResult} */
+    const relay = {
+        kind: 'relay',
+        teamCode: teamMap.get(currentTeam)?.code || currentTeam || slice(f1, 2, 6),
+        relayLetter: slice(f1, 7, 8),
+        seedTime: timeFromSeconds(num(f1.slice(52, 59))),
+        finalTime: timeFromSeconds(seconds),
+        status,
+        disqualified: status === 'dq',
+        place: Number.isNaN(place) ? null : place || null,
+        points: 0,
+        legs: [],
+    };
+    ev.results.push(relay);
+    return relay;
+}
+
+function parseRelayLegs(f3, relay, athletes) {
+    // Up to 8 slots of 13 chars starting at col 3 (index 2).
+    for (let off = 2; off + 13 <= f3.length; off += 13) {
+        const slot = f3.slice(off, off + 13);
+        const anum = slot.slice(1, 6).trim();
+        if (!anum) continue;
+        const leg = parseInt(slot.slice(12, 13), 10);
+        const a = athletes.get(anum);
+        relay.legs.push({
+            name: a ? athleteName(a) : slot.slice(6, 11).trim(),
+            gender: a && (a.gender === 'M' || a.gender === 'F') ? a.gender : undefined,
+            legOrder: Number.isNaN(leg) ? relay.legs.length + 1 : leg,
+        });
+    }
+}
+
+function buildEvent(line, type, off) {
+    const gender = EVENT_SEX[line[off.sex[0]]] || 'X';
+    const distance = parseInt(slice(line, off.dist[0], off.dist[1]), 10) || 0;
+    const strokeCode = line[off.stroke[0]];
+    const strokeMap = type === 'relay' ? HY3_RELAY_STROKE : HY3_STROKE;
+    const stroke = strokeMap[strokeCode] || `Stroke ${strokeCode}`;
+    const ageRaw = slice(line, off.age[0], off.age[1]).split(/\s+/).filter(Boolean);
+    const ag = ageGroup(ageRaw[0], ageRaw[1]);
+    const agLabel = type === 'relay' && ag.label === 'Open' ? '' : ag.label;
+    const description = `${GENDER_DISPLAY[gender]} ${agLabel} ${distance}m ${stroke}${type === 'relay' ? ' Relay' : ''}`
+        .replace(/\s+/g, ' ')
+        .trim();
+    return { type, gender, distance, stroke, ageGroup: ag, description, results: [] };
+}
+
+function ensureEvent(eventMap, built, rawNumber) {
+    const numbered = rawNumber && rawNumber !== '0';
+    const key = numbered ? rawNumber : `u:${built.description}`;
+    let ev = eventMap.get(key);
+    if (!ev) {
+        ev = { number: numbered ? rawNumber : '', ...built };
+        eventMap.set(key, ev);
+    }
+    return ev;
+}

package/src/index.js

@@ -0,0 +1,49 @@
+/**
+ * swimparse — public entry point.
+ *
+ * Parse SDIF v3 (.sd3) or Hy-Tek (.hy3) meet results into one NormalizedMeet.
+ * Zero dependencies; runs in the browser, Node, and CI.
+ *
+ *   import { parse, detectFormat } from 'swimparse';
+ *   const meet = parse(fileText, { filename: 'GG_at_WW.hy3' });
+ *
+ * SCOPE: this library reads meet-result files and emits JSON. That is all it
+ * does. It has no concept of a league — no age bands, no scoring rules, no team
+ * registry, no qualifying standards. Those are league policy and belong to the
+ * application consuming this output.
+ *
+ * PRIVACY: the output is a lossless superset of the source file, so it CARRIES
+ * SWIMMER BIRTHDATES (`swimmers[].birthDate`, individual `results[].birthDate`)
+ * and USA-S registration ids. For youth meets that is PII for minors — treat
+ * every parse result as confidential until your application has stripped or
+ * aggregated it. swimparse deliberately does not do that for you: what counts as
+ * safe is a league decision (a summer league publishes age-group labels; a
+ * USA-Swimming tool needs exact ages), so it belongs to the consumer.
+ */
+
+import { parseSdif } from './sdif.js';
+import { parseHy3 } from './hy3.js';
+import { detectFormat } from './detect.js';
+
+export { parseSdif } from './sdif.js';
+export { parseHy3 } from './hy3.js';
+export { detectFormat } from './detect.js';
+export * from './model.js';
+export * from './constants.js';
+export * from './times.js';
+
+/**
+ * Parses meet-result text, auto-detecting the format unless one is given.
+ *
+ * @param {string} content
+ * @param {Object} [opts]
+ * @param {'sdif-v3'|'hy3'} [opts.format] force a format, skipping detection
+ * @param {string} [opts.filename] used as a detection tie-breaker
+ * @returns {import('./model.js').NormalizedMeet}
+ */
+export function parse(content, opts = {}) {
+    const format = opts.format || detectFormat(content, opts.filename);
+    if (format === 'sdif-v3') return parseSdif(content);
+    if (format === 'hy3') return parseHy3(content);
+    throw new Error('swimparse: could not detect meet-result format (expected SDIF .sd3 or Hy-Tek .hy3)');
+}

package/src/model.js

@@ -0,0 +1,211 @@
+/**
+ * The NormalizedMeet contract.
+ *
+ * The single shape both adapters produce, so consumers read one JSON contract
+ * instead of two fixed-width formats.
+ *
+ * Design rule: **lossless superset**. Capture every swim — placing or not,
+ * exhibition, DQ, no-show — plus birthdates, seed times, splits and DQ reasons.
+ * Consumers filter down to what they need. Never drop data at parse time.
+ *
+ * Everything here is read out of the file. Nothing is inferred, computed, or
+ * relabelled according to any league's rules: no age banding, no scoring, no
+ * team-code canonicalization, no synthesized meet names. Those are consumer
+ * concerns.
+ *
+ * PRIVACY: `swimmers[].birthDate` and `usasId` are PII for minors, and the
+ * lossless rule means they are always populated when the file carries them. A
+ * NormalizedMeet is therefore a confidential artifact by default. Stripping or
+ * aggregating it is the consumer's job — see the privacy note in index.js.
+ */
+
+/**
+ * @typedef {import('./times.js').SwimTime} SwimTime
+ */
+
+/**
+ * @typedef {Object} NormalizedMeet
+ * @property {'sdif-v3'|'hy3'} format         Source format the file was parsed from.
+ * @property {Object} source                  Producing software (A0/A1 record).
+ * @property {string} [source.software]
+ * @property {string} [source.version]
+ * @property {string} [source.createdAt]      ISO date if available.
+ * @property {MeetInfo} meet
+ * @property {Team[]} teams
+ * @property {Swimmer[]} swimmers             Deduped registry (name + birthdate).
+ * @property {Event[]} events
+ */
+
+/**
+ * @typedef {Object} MeetInfo
+ * @property {string} name                    Meet name as it appeared in the file.
+ * @property {string} rawName                 Identical to `name`; kept so consumers
+ *                                            that relabel a meet have an untouched
+ *                                            original to fall back on.
+ * @property {string} [hostName]
+ * @property {string|null} startDate          ISO "YYYY-MM-DD".
+ * @property {string|null} [endDate]
+ * @property {string|null} [course]           'SCY' | 'LCM' | 'SCM'.
+ */
+
+/**
+ * @typedef {Object} Team
+ * @property {string} code                    Display code, VA-prefix stripped (e.g. "WW").
+ * @property {string} fullCode                Raw code as in the file (e.g. "VAWW").
+ * @property {string} name
+ * @property {string} [shortName]
+ */
+
+/**
+ * @typedef {Object} Swimmer
+ * @property {string} id                      Stable within-file id.
+ * @property {string} teamCode
+ * @property {string} lastName
+ * @property {string} firstName
+ * @property {string} [preferredName]
+ * @property {string} [middleInitial]
+ * @property {string} fullName                "Last, First".
+ * @property {'M'|'F'} [gender]
+ * @property {string|null} [birthDate]        ISO, or null. PII — as read from the file.
+ * @property {string|null} [usasId]           PII — as read from the file.
+ * @property {number|null} [age]              Age as stated in the file, when present.
+ */
+
+/**
+ * @typedef {Object} Event
+ * @property {string} number                  Event number as a string (may be alphanumeric).
+ * @property {'individual'|'relay'} type
+ * @property {'M'|'F'|'X'} gender
+ * @property {number} distance
+ * @property {string} stroke                  Canonical stroke name.
+ * @property {string|null} [course]
+ * @property {{label:string, lower:number, upper:number}} ageGroup
+ * @property {string} description             Human label, e.g. "Boys 15-18 100m IM".
+ * @property {(IndividualResult|RelayResult)[]} results
+ */
+
+/**
+ * @typedef {Object} IndividualResult
+ * @property {'individual'} kind
+ * @property {string} [swimmerId]             Links to Swimmer.id when resolvable.
+ * @property {string} swimmerName             "Last, First" as in the file.
+ * @property {string} teamCode
+ * @property {string|null} [birthDate]        ISO. PII — as read from the file.
+ * @property {SwimTime|null} seedTime
+ * @property {SwimTime|null} finalTime        The time swum. NOTE: for HY3 this is
+ *                                            retained even on a DQ; for SDIF it is
+ *                                            null on DQ/NS (the format nulls it).
+ * @property {import('./constants.js').ResultStatus} status
+ * @property {boolean} disqualified
+ * @property {string} [dqCode]                HY3 only.
+ * @property {string} [dqReason]              HY3 H1/H2 only.
+ * @property {number|null} place              null = non-scoring / exhibition.
+ * @property {number} [heat]
+ * @property {number} [lane]
+ * @property {number} points                  Points as stored in the file (SDIF).
+ *                                            HY3 carries none, so it reads 0 —
+ *                                            deriving points is a scoring concern
+ *                                            and belongs to the consumer.
+ * @property {number[]} [splits]              Cumulative split seconds (HY3 G1).
+ */
+
+/**
+ * @typedef {Object} RelayResult
+ * @property {'relay'} kind
+ * @property {string} teamCode
+ * @property {string} relayLetter             'A', 'B', ...
+ * @property {SwimTime|null} seedTime
+ * @property {SwimTime|null} finalTime
+ * @property {import('./constants.js').ResultStatus} status
+ * @property {boolean} disqualified
+ * @property {string} [dqCode]
+ * @property {string} [dqReason]
+ * @property {number|null} place
+ * @property {number} [heat]
+ * @property {number} [lane]
+ * @property {number} points
+ * @property {RelayLeg[]} legs
+ * @property {number[]} [splits]
+ */
+
+/**
+ * @typedef {Object} RelayLeg
+ * @property {string} [swimmerId]
+ * @property {string} name
+ * @property {'M'|'F'} [gender]
+ * @property {number} [age]
+ * @property {number} legOrder                1-4 (or higher for alternates).
+ */
+
+/**
+ * Strips a two-letter LSC/state prefix (e.g. "VAWW" → "WW") from a raw team code.
+ *
+ * This is an SDIF/HY3 file convention, not a league rule: US meet files prefix
+ * team codes with the LSC. `Team.fullCode` always keeps the raw value, so a
+ * consumer that wants the prefix back has it. Mapping either form onto a
+ * league's canonical code is the consumer's job.
+ *
+ * @param {string} rawCode
+ * @returns {string}
+ */
+export function displayTeamCode(rawCode) {
+    const c = (rawCode || '').trim();
+    return c.startsWith('VA') ? c.slice(2) : c;
+}
+
+/**
+ * Builds the deduped swimmer registry from individual results.
+ *
+ * Keyed on `lastName|firstName|birthDate`, the strongest identity the file
+ * itself supports (middle name is excluded because it drifts between exports).
+ * This is a **within-file** key only — durable cross-meet or cross-season
+ * athlete identity is a consumer concern and cannot be decided here.
+ *
+ * @param {Event[]} events
+ * @param {Map<string, Partial<Swimmer>>} [enrich] optional id→extra fields (D3/D1 data)
+ * @returns {Swimmer[]}
+ */
+export function deriveSwimmers(events, enrich) {
+    /** @type {Map<string, Swimmer>} */
+    const byKey = new Map();
+    for (const ev of events) {
+        if (ev.type !== 'individual') continue;
+        const gender = ev.gender === 'X' ? undefined : ev.gender;
+        for (const r of ev.results) {
+            const [last, first] = splitName(r.swimmerName);
+            const key = `${last}|${first}|${r.birthDate || ''}`.toLowerCase();
+            if (!byKey.has(key)) {
+                byKey.set(key, {
+                    id: key,
+                    teamCode: r.teamCode,
+                    lastName: last,
+                    firstName: first,
+                    fullName: r.swimmerName,
+                    gender,
+                    birthDate: r.birthDate || null,
+                    usasId: null,
+                });
+            }
+            r.swimmerId = key;
+        }
+    }
+    if (enrich) {
+        for (const s of byKey.values()) {
+            const extra = enrich.get(s.id);
+            if (extra) Object.assign(s, extra);
+        }
+    }
+    return [...byKey.values()];
+}
+
+/**
+ * Splits "Last, First M" into ["Last", "First"] (middle dropped).
+ * @param {string} name
+ * @returns {[string, string]}
+ */
+export function splitName(name) {
+    const parts = String(name || '').split(',');
+    const last = (parts[0] || '').trim();
+    const first = (parts[1] || '').trim().split(/\s+/)[0] || '';
+    return [last, first];
+}

package/src/sdif.js

@@ -0,0 +1,188 @@
+/**
+ * SDIF v3 (.sd3) adapter → NormalizedMeet.
+ *
+ * Fixed-width text. Record types handled:
+ *   B1 meet · B2 host · C1 team · D0 individual result · D3 swimmer reg
+ *   E0 relay result · F0 relay swimmer
+ *
+ * Keeps EVERY individual/relay result (exhibition, DQ, no-show, non-placing)
+ * — the lossless-superset rule.
+ */
+
+import { SDIF_STROKE, GENDER, GENDER_DISPLAY, ageGroup } from './constants.js';
+import { timeFromText, normalizeDate } from './times.js';
+import { displayTeamCode, deriveSwimmers } from './model.js';
+
+// Column offsets (0-indexed, [start, end)).
+const OFF = {
+    D0: { name: [11, 39], birth: [55, 63], seed: [88, 96], final: [115, 123], event: [72, 76], place: [135, 138], points: [138, 142] },
+    D0evt: { gender: [66, 67], dist: [67, 71], stroke: [71, 72], age: [76, 80] },
+    E0: { letter: [11, 12], final: [72, 80], event: [26, 30], place: [92, 95], points: [95, 99] },
+    E0evt: { gender: [20, 21], dist: [21, 25], stroke: [25, 26], age: [30, 34] },
+    F0: { name: [22, 50] },
+};
+
+const slice = (line, [a, b]) => (line.length >= a ? line.slice(a, b).trim() : '');
+
+/**
+ * @param {string} content raw .sd3 text
+ * @returns {import('./model.js').NormalizedMeet}
+ */
+export function parseSdif(content) {
+    const lines = String(content).split(/\r?\n/);
+
+    /** @type {import('./model.js').MeetInfo} */
+    const meet = { name: '', rawName: '', startDate: null };
+    /** @type {Map<string, import('./model.js').Team>} */
+    const teamMap = new Map();
+    /** @type {Map<string, import('./model.js').Event>} */
+    const eventMap = new Map();
+
+    let currentTeam = null; // raw code
+    let lastRelay = null;
+
+    const source = {};
+
+    for (const line of lines) {
+        const code = line.slice(0, 2);
+        try {
+            switch (code) {
+                case 'A0':
+                    source.software = slice(line, [43, 63]) || undefined;
+                    break;
+                case 'B1':
+                    meet.rawName = slice(line, [11, 41]);
+                    meet.name = meet.rawName;
+                    meet.startDate = normalizeDate(slice(line, [121, 129]));
+                    lastRelay = null;
+                    break;
+                case 'B2':
+                    if (!meet.hostName) meet.hostName = slice(line, [11, 41]);
+                    break;
+                case 'C1': {
+                    const raw = slice(line, [11, 17]);
+                    currentTeam = raw;
+                    if (!teamMap.has(raw)) {
+                        teamMap.set(raw, {
+                            code: displayTeamCode(raw),
+                            fullCode: raw,
+                            name: slice(line, [17, 47]),
+                        });
+                    }
+                    lastRelay = null;
+                    break;
+                }
+                case 'D0':
+                    lastRelay = null;
+                    parseD0(line, eventMap, currentTeam, teamMap);
+                    break;
+                case 'E0':
+                    lastRelay = parseE0(line, eventMap, currentTeam, teamMap);
+                    break;
+                case 'F0':
+                    if (lastRelay) {
+                        const name = slice(line, OFF.F0.name);
+                        if (name) lastRelay.legs.push({ name, legOrder: lastRelay.legs.length + 1 });
+                    }
+                    break;
+            }
+        } catch {
+            /* skip malformed line */
+        }
+    }
+
+    const events = [...eventMap.values()];
+    for (const ev of events) {
+        ev.results.sort((a, b) => (a.place ?? 999) - (b.place ?? 999));
+    }
+    const teams = [...teamMap.values()];
+    const swimmers = deriveSwimmers(events);
+
+    return { format: 'sdif-v3', source, meet, teams, swimmers, events };
+}
+
+function statusFromText(raw) {
+    const t = String(raw).trim().toUpperCase();
+    if (t.startsWith('DQ')) return 'dq';
+    if (t.startsWith('NS')) return 'ns';
+    if (t.startsWith('DNF')) return 'dnf';
+    if (t.startsWith('SCR')) return 'scratch';
+    return 'ok';
+}
+
+function parseD0(line, eventMap, currentTeam, teamMap) {
+    if (!currentTeam) return;
+    // Event number 0 = an unseeded/unofficial event (e.g. 8 & Under "B" relays).
+    // Keep it (lossless), but bucket unnumbered events by description so two
+    // distinct ones don't merge under a shared "0".
+    const eventNum = slice(line, OFF.D0.event);
+    const ev = ensureEvent(eventMap, buildEvent(line, 'individual', OFF.D0evt), eventNum);
+
+    const finalRaw = slice(line, OFF.D0.final);
+    const status = statusFromText(finalRaw);
+    const placeNum = parseInt(slice(line, OFF.D0.place), 10);
+
+    /** @type {import('./model.js').IndividualResult} */
+    ev.results.push({
+        kind: 'individual',
+        swimmerName: slice(line, OFF.D0.name),
+        teamCode: teamMap.get(currentTeam)?.code || currentTeam,
+        birthDate: normalizeDate(slice(line, OFF.D0.birth)),
+        seedTime: timeFromText(slice(line, OFF.D0.seed)),
+        finalTime: status === 'ok' ? timeFromText(finalRaw) : null,
+        status,
+        disqualified: status === 'dq',
+        place: Number.isNaN(placeNum) ? null : placeNum || null,
+        points: parseFloat(slice(line, OFF.D0.points)) || 0,
+    });
+}
+
+function parseE0(line, eventMap, currentTeam, teamMap) {
+    if (!currentTeam) return null;
+    const eventNum = slice(line, OFF.E0.event);
+    const ev = ensureEvent(eventMap, buildEvent(line, 'relay', OFF.E0evt), eventNum);
+
+    const finalRaw = slice(line, OFF.E0.final);
+    const status = statusFromText(finalRaw);
+    const placeNum = parseInt(slice(line, OFF.E0.place), 10);
+
+    /** @type {import('./model.js').RelayResult} */
+    const relay = {
+        kind: 'relay',
+        teamCode: teamMap.get(currentTeam)?.code || currentTeam,
+        relayLetter: slice(line, OFF.E0.letter),
+        seedTime: null,
+        finalTime: status === 'ok' ? timeFromText(finalRaw) : null,
+        status,
+        disqualified: status === 'dq',
+        place: Number.isNaN(placeNum) ? null : placeNum || null,
+        points: parseFloat(slice(line, OFF.E0.points)) || 0,
+        legs: [],
+    };
+    ev.results.push(relay);
+    return relay;
+}
+
+function buildEvent(line, type, off) {
+    const gender = GENDER[slice(line, off.gender)] || 'X';
+    const distance = parseInt(slice(line, off.dist), 10) || 0;
+    const stroke = SDIF_STROKE[slice(line, off.stroke)] || `Stroke ${slice(line, off.stroke)}`;
+    const ageCode = slice(line, off.age).padEnd(4);
+    const ag = ageGroup(ageCode.slice(0, 2), ageCode.slice(2, 4));
+    const agLabel = type === 'relay' && ag.label === 'Open' ? '' : ag.label;
+    const description = `${GENDER_DISPLAY[gender]} ${agLabel} ${distance}m ${stroke}${type === 'relay' ? ' Relay' : ''}`
+        .replace(/\s+/g, ' ')
+        .trim();
+    return { type, gender, distance, stroke, ageGroup: ag, description, results: [] };
+}
+
+function ensureEvent(eventMap, built, rawNumber) {
+    const numbered = rawNumber && rawNumber !== '0';
+    const key = numbered ? rawNumber : `u:${built.description}`;
+    let ev = eventMap.get(key);
+    if (!ev) {
+        ev = { number: numbered ? rawNumber : '', ...built };
+        eventMap.set(key, ev);
+    }
+    return ev;
+}

package/src/times.js

@@ -0,0 +1,99 @@
+/**
+ * Time and date helpers.
+ *
+ * The two source formats encode times differently — SDIF as display text
+ * ("1:11.35"), HY3 as raw seconds ("71.35") — but a NormalizedMeet always
+ * carries BOTH: `{ text, seconds }`. These helpers convert either way.
+ */
+
+/**
+ * @typedef {Object} SwimTime
+ * @property {string} text     Canonical display, e.g. "1:11.35" or "28.05".
+ * @property {number} seconds  Total seconds as a float (hundredths precision).
+ */
+
+/**
+ * Parses an SDIF-style time string into seconds.
+ * Handles "MM:SS.ss", "SS.ss", optional trailing course letter, and the
+ * non-time sentinels DQ / NS / SCR / DNF / NT (→ null).
+ *
+ * @param {string} raw
+ * @returns {number|null} seconds, or null if not a real time
+ */
+export function textToSeconds(raw) {
+    if (!raw) return null;
+    const s = String(raw).trim().replace(/[A-Za-z]+$/, '').trim(); // strip trailing course flag
+    if (!s) return null;
+    if (/^(DQ|NS|SCR|DNF|NT)$/i.test(String(raw).trim())) return null;
+    if (s.includes(':')) {
+        const [m, rest] = s.split(':');
+        const minutes = parseInt(m, 10);
+        const seconds = parseFloat(rest);
+        if (Number.isNaN(minutes) || Number.isNaN(seconds)) return null;
+        return round2(minutes * 60 + seconds);
+    }
+    const v = parseFloat(s);
+    return Number.isNaN(v) || v <= 0 ? null : round2(v);
+}
+
+/**
+ * Formats seconds as canonical display text ("1:11.35", "28.05").
+ * @param {number|null} seconds
+ * @returns {string}
+ */
+export function secondsToText(seconds) {
+    if (seconds == null || Number.isNaN(seconds) || seconds <= 0) return '';
+    const total = round2(seconds);
+    const m = Math.floor(total / 60);
+    const s = total - m * 60;
+    if (m > 0) return `${m}:${s.toFixed(2).padStart(5, '0')}`;
+    return s.toFixed(2);
+}
+
+/**
+ * Builds a SwimTime from seconds (HY3 path). Returns null if not a real time.
+ * @param {number|null} seconds
+ * @returns {SwimTime|null}
+ */
+export function timeFromSeconds(seconds) {
+    if (seconds == null || Number.isNaN(seconds) || seconds <= 0) return null;
+    return { text: secondsToText(seconds), seconds: round2(seconds) };
+}
+
+/**
+ * Builds a SwimTime from display text (SDIF path). Returns null if not a real time.
+ * @param {string} text
+ * @returns {SwimTime|null}
+ */
+export function timeFromText(text) {
+    const seconds = textToSeconds(text);
+    return seconds == null ? null : { text: secondsToText(seconds), seconds };
+}
+
+/**
+ * Normalizes an MMDDYYYY (or MMDDYY) date to ISO "YYYY-MM-DD".
+ * Two-digit years are windowed: <30 → 20xx, else 19xx.
+ * @param {string} raw
+ * @returns {string|null}
+ */
+export function normalizeDate(raw) {
+    if (!raw) return null;
+    const d = String(raw).trim();
+    if (d.length === 8) {
+        const mm = d.slice(0, 2), dd = d.slice(2, 4), yyyy = d.slice(4, 8);
+        if (yyyy === '0000' || mm === '00') return null;
+        return `${yyyy}-${mm}-${dd}`;
+    }
+    if (d.length === 6) {
+        const mm = d.slice(0, 2), dd = d.slice(2, 4), yy = parseInt(d.slice(4, 6), 10);
+        if (Number.isNaN(yy)) return null;
+        const yyyy = yy < 30 ? 2000 + yy : 1900 + yy;
+        return `${yyyy}-${mm}-${dd}`;
+    }
+    return null;
+}
+
+/** Rounds to hundredths, avoiding binary-float noise. */
+export function round2(n) {
+    return Math.round((n + Number.EPSILON) * 100) / 100;
+}