edf2csv 0.5.57 → 0.5.59

package/CHANGELOG.md

@@ -3,6 +3,66 @@
 Notable changes to edf2csv. Versions follow [semantic versioning](https://semver.org); while the
 major version is 0, a minor bump may contain breaking changes.
 
+## 0.5.59
+
+### Fixed: `--info` never said where a recording starts, on the recordings that do not start at zero
+
+0.4.9 made the first data record's timekeeping annotation the point a recording is timed
+from. A file whose first record says `+1000` therefore writes `time_s` from `1000.000`, and
+`--start` and `--end` are read on that same clock. None of that appeared in `--info`, which
+said
+
+```
+Duration   3s  (3 records of 1s)
+```
+
+and nothing else — three seconds, which reads as 0 to 3. `--start 0 --end 1` on that file
+then converted nothing and explained: "The window is inside the recording but lands where
+there is no data — past the last sample, or inside a gap in a discontinuous file. Run with
+--info to see where the records actually sit." `--info` was the one place the number was
+missing, and the advice was a loop.
+
+It is printed now, whenever it is not zero, and in seconds rather than through the duration
+formatter — this number exists to be typed back in, and `--start` takes `1000s` where it does
+not take "16m 40s":
+
+```
+Duration   3s  (3 records of 1s)
+Timed from 1000.000s  (first sample; --start and --end use this clock)
+```
+
+Under `--json` it is `first_sample_seconds`. `duration_seconds` and `time_span_seconds` were
+both already there and are both lengths; neither says where the length sits. The value was
+already in `plan.range` and already governed the row estimate printed underneath — it was
+simply never shown. A recording timed from zero, which is nearly all of them, gains no line.
+
+## 0.5.58
+
+### Fixed: a duration below zero was exported without comment
+
+`+0.1<0x15>-3<0x14>backwards` parses perfectly. It came out as
+
+```
+onset_s,duration_s,description,record_index
+0.1,-3,backwards,0
+```
+
+with nothing on stderr and nothing in metadata.json, and there is nothing about that row to
+look at twice. A duration is a length of time and a length below zero is not one, so every
+use of it goes quietly wrong — starting with the recipe this project's own annotations page
+gives for the samples an event covers, `onset_s + duration_s`, which for -3 ends the window
+three seconds before the event begins and selects nothing at all.
+
+The value is still written exactly as the file gave it. Replacing it with a zero, or emptying
+the cell, would put a number in annotations.csv that no writer wrote, and not inventing
+numbers is the point of the tool. What it does now is say so: "1 annotation states a duration
+below zero, which is not a length of time", with the arithmetic spelled out in the hint.
+
+Counted apart from a duration that could not be read, which 0.5.55 added — that one failed to
+parse and lost its value, this one parsed and kept it, and what is wrong is arithmetic rather
+than decoding. `readAnnotations()` returns the new count as `negativeDurations`, documented
+alongside the other three, and a duration of exactly zero is not negative.
+
 ## 0.5.57
 
 ### Fixed: api.md's `readAnnotations()` signature was missing two of its three counts

package/dist/cli/report.js

@@ -77,6 +77,25 @@ export function formatInfo(file, plan) {
     if (Math.abs(elapsedSpan - file.durationSeconds) > 1e-9) {
         lines.push(`Time span  ${formatDuration(elapsedSpan)}  (includes discontinuities)`);
     }
+    /*
+      Where the samples begin, when that is not zero.
+  
+      0.4.9 made the first record's timekeeping TAL the point a recording is timed from, so a
+      file whose TALs start at +1000 writes `time_s` from 1000.000 and takes `--start` and
+      `--end` on that same clock. None of that appeared here: the report said "Duration 3s",
+      which reads as 0 to 3, and `--start 0 --end 1` then selected nothing and answered with
+      "The window is inside the recording but lands where there is no data ... Run with --info
+      to see where the records actually sit" — pointing at this report, which was the one place
+      the number was missing. It is in `plan.range` already and governs the estimate printed
+      below; it was simply never shown.
+    */
+    const startsAt = plan.range.recordingStartSeconds;
+    if (Number.isFinite(startsAt) && Math.abs(startsAt) > 1e-9) {
+        // In seconds rather than through formatDuration, because this number is meant to be
+        // typed back in: `--start` takes `1000s`, and "16m 40s" is not something it accepts.
+        // It is also how the empty-window warning renders the window it was given.
+        lines.push(`Timed from ${startsAt.toFixed(3)}s  (first sample; --start and --end use this clock)`);
+    }
     lines.push(`Size       ${formatBytes(file.fileSize)}`);
     if (header.patientId)
         lines.push(`Patient    ${printable(header.patientId)}`);
@@ -210,6 +229,10 @@ export function infoJson(file, plan, indent = 2) {
         duration_seconds: file.durationSeconds,
         // For a discontinuous file this exceeds duration_seconds by the length of the gaps.
         time_span_seconds: plan.range.recordingEndSeconds - plan.range.recordingStartSeconds,
+        // Where `time_s` begins, and the clock `--start` and `--end` are read against. Usually
+        // zero; not when the first record's timekeeping TAL puts the recording elsewhere. Both
+        // of the fields above are lengths and neither says where that length sits.
+        first_sample_seconds: plan.range.recordingStartSeconds,
         annotation_channels: file.annotationSignals.length,
         channels: file.dataSignals.map((signal) => ({
             signal_index: signal.index,

package/dist/cli/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Human-readable output for the terminal.\n *\n * Everything here is plain text with no colour codes, so piping to a file or a log\n * produces exactly what appeared on screen.\n */\n\nimport type { Diagnostic } from '../edf/errors.js';\nimport type { EdfFile } from '../edf/reader.js';\nimport { describeFormat, formatRates, formatWallClock } from '../edf/header.js';\nimport { formatBytes, formatDuration } from '../format/number.js';\nimport type { ConversionPlan } from '../convert/plan.js';\nimport { withoutFileRateWarning } from '../convert/plan.js';\nimport type { ConvertResult } from '../convert/run.js';\n\nfunction table(rows: readonly (readonly string[])[], alignRight: ReadonlySet<number>): string {\n  if (rows.length === 0) return '';\n  const width: number[] = [];\n  for (const row of rows) {\n    row.forEach((cell, i) => {\n      width[i] = Math.max(width[i] ?? 0, cell.length);\n    });\n  }\n  return rows\n    .map((row) =>\n      row\n        .map((cell, i) => {\n          const w = width[i] ?? 0;\n          return alignRight.has(i) ? cell.padStart(w) : cell.padEnd(w);\n        })\n        .join('  ')\n        .trimEnd(),\n    )\n    .join('\\n');\n}\n\n/**\n * Make header text safe to print to a terminal.\n *\n * EDF identification fields and channel labels are free text copied verbatim out of the\n * file, and `--info` puts them straight on stdout. A header carrying ANSI escapes could\n * therefore drive the reader's terminal — `\\x1b[2J\\x1b[H` clears the screen and homes the\n * cursor, which is enough to hide the rest of the output or repaint it as something else.\n * Nobody writes an EDF header that way on purpose, which is exactly why a file that does\n * should not be trusted with the terminal.\n *\n * Control bytes are shown as their escape instead, so a corrupt field stays diagnosable\n * rather than being silently swallowed. This affects display only: `channels.csv` and\n * `metadata.json` still copy the field verbatim, and CSV quoting already makes that safe.\n */\nexport function printable(text: string): string {\n  // eslint-disable-next-line no-control-regex\n  return text.replace(/[\\u0000-\\u001f\\u007f-\\u009f]/gu, (c) =>\n    `\\\\x${c.codePointAt(0)!.toString(16).padStart(2, '0')}`,\n  );\n}\n\n/**\n * The same protection for text that is meant to span lines.\n *\n * `printable` escapes newlines along with everything else, which is right for a channel\n * label — one has no business containing a line break, and it would break the `--info`\n * table's alignment. It is wrong for a whole message: several are written on two lines,\n * and Node's own option errors run to three. Escaping those turned the break into text:\n *\n *     error: No channel named \"ECQ\". Did you mean \"ECG\"?\\x0aRun with --info to list ...\n *\n * Each line is escaped on its own, so nothing here gains the ability to drive a terminal.\n * A carriage return is still escaped, so no line can be repainted after it is printed —\n * which is the property that mattered. A newline can only add a line, never overwrite one.\n */\nexport function printableLines(text: string, indent = ''): string {\n  return text\n    .split('\\n')\n    .map((line, index) => (index === 0 ? '' : indent) + printable(line))\n    .join('\\n');\n}\n\n/** The `--info` view: what is in this recording, and what would converting it produce. */\nexport function formatInfo(file: EdfFile, plan: ConversionPlan): string {\n  const { header } = file;\n  const lines: string[] = [];\n\n  lines.push(`File       ${file.path}`);\n  lines.push(`Format     ${describeFormat(header)}`);\n  lines.push(\n    `Recorded   ${\n      formatWallClock(header.startDateTime)?.replace('T', ' ') ??\n      `${printable(header.startDateRaw)} ${printable(header.startTimeRaw)} (unparseable)`\n    }`,\n  );\n  lines.push(\n    `Duration   ${formatDuration(file.durationSeconds)}  (${file.recordCount} records of ${header.recordDuration}s)`,\n  );\n  const elapsedSpan = plan.range.recordingEndSeconds - plan.range.recordingStartSeconds;\n  if (Math.abs(elapsedSpan - file.durationSeconds) > 1e-9) {\n    lines.push(`Time span  ${formatDuration(elapsedSpan)}  (includes discontinuities)`);\n  }\n  lines.push(`Size       ${formatBytes(file.fileSize)}`);\n  if (header.patientId) lines.push(`Patient    ${printable(header.patientId)}`);\n  if (header.recordingId) lines.push(`Recording  ${printable(header.recordingId)}`);\n\n  const signals = file.dataSignals;\n  lines.push('');\n  // The signal count was pluralised but the annotation-channel count was not, so a file\n  // carrying two of them read \"2 annotation channel\". EDF+ permits more than one.\n  const annotationCount = file.annotationSignals.length;\n  const annotationPart =\n    annotationCount > 0\n      ? ` + ${annotationCount} annotation channel${annotationCount === 1 ? '' : 's'}`\n      : '';\n  lines.push(\n    `Channels   ${signals.length} signal${signals.length === 1 ? '' : 's'}${annotationPart}`,\n  );\n  lines.push('');\n\n  const rows: string[][] = [['#', 'COLUMN', 'LABEL', 'UNIT', 'RATE', 'RANGE', 'OUTPUT']];\n  const fileFor = new Map<number, string>();\n  for (const group of plan.groups) {\n    for (const channel of group.channels) fileFor.set(channel.signal.index, group.fileName);\n  }\n  // Rendered as a group so that two channels recorded at different rates never show the\n  // same figure in the RATE column, which is the one thing this table is asked to settle.\n  const rateText = formatRates(signals.map((signal) => signal.samplingRate));\n  for (const [row, signal] of signals.entries()) {\n    rows.push([\n      String(signal.index),\n      printable(plan.columnNames.get(signal.index) ?? ''),\n      printable(signal.label),\n      printable(signal.physicalDimension),\n      `${rateText[row]} Hz`,\n      `${signal.physicalMin} to ${signal.physicalMax}`,\n      /*\n        A channel with no samples was reported as \"(not selected)\", which is a different\n        thing and not true when it was named on --channels. `edf2csv rec.edf --info\n        --channels unused` said the channel the command asked for had not been chosen, when\n        what is actually the case is that the file gives it nothing to convert. The\n        NO_SAMPLES warning below the table says so; the table contradicted it.\n      */\n      fileFor.get(signal.index) ??\n        (signal.samplesPerRecord === 0 ? '(no samples)' : '(not selected)'),\n    ]);\n  }\n  lines.push(table(rows, new Set([0])));\n\n  lines.push('');\n  if (plan.groups.length > 1) {\n    lines.push(\n      plan.layout === 'long'\n        ? `Sampling rates differ, and the long layout puts them in one table anyway: each row ` +\n          `carries its own time, so nothing has to line up. No channel is resampled.`\n        : `Sampling rates differ, so channels are written to ${plan.groups.length} files, one per rate. ` +\n          `No channel is resampled.`,\n    );\n  }\n  /*\n    The estimate describes the signal tables, and says so when that is not what will be\n    written.\n\n    Under --annotations-only there are no signal tables, and the line read \"Would write 0\n    rows, roughly 0 B.\" for a conversion that goes on to write annotations.csv with three\n    events in it. --info exists to say what a conversion will do; asserting it will write\n    nothing, when it will write a file, is the one thing it must not do.\n\n    How many events there are cannot be answered from the header — the annotation channel has\n    to be read record by record, which is the scan --info is for avoiding. So it says which\n    file, and that the count is not knowable this cheaply, rather than inventing a zero.\n  */\n  /*\n    No signal table to describe, whichever way that came about.\n\n    This asked only whether `--annotations-only` had been given. A recording that has no\n    signal channels — one holding nothing but EDF+ annotations — has none either, and fell\n    through to the estimate line: \"Would write 0 rows, roughly 0 B.\" for a conversion that\n    goes on to write an annotations.csv with events in it, beside channels.csv and\n    metadata.json. That is the sentence 0.4.51 removed, arriving by the other route.\n  */\n  if (!plan.writeSignals || plan.groups.length === 0) {\n    // Named as they will be written. --info is read to find out what a run leaves behind,\n    // and a script that opens the name it was given must find a file there.\n    const suffix = plan.gzip ? '.csv.gz' : '.csv';\n    lines.push(\n      file.annotationSignals.length > 0\n        ? `Would write annotations${suffix} and channels${suffix}, and no signal data. How ` +\n          'many events there are cannot be told from the header.'\n        : `Would write channels${suffix} and no signal data — and no annotations${suffix} ` +\n          'either, since this recording has no annotation channel.',\n    );\n    return lines.join('\\n');\n  }\n\n  // The estimate counts the characters of the CSV, which is what --gzip then compresses.\n  // Reporting it as the size on disk would overstate a compressed conversion several-fold.\n  const compressing = plan.gzip;\n  lines.push(\n    `Would write ${plan.estimate.rows.toLocaleString('en-US')} rows, roughly ` +\n      `${formatBytes(plan.estimate.bytes)}${compressing ? ' before compression' : ''}.`,\n  );\n\n  return lines.join('\\n');\n}\n\n/**\n * The `--info` view as JSON, for surveying files from a script.\n *\n * `indent` is 2 for a single recording, matching what this has always printed, and null for\n * a batch — several pretty-printed documents run together are readable by a streaming parser\n * but not by anything that expects one record per line, and a batch is exactly where\n * line-oriented reading is wanted. null rather than undefined because a default parameter\n * takes effect when undefined is passed, which quietly restored the indentation this was\n * meant to drop; JSON.stringify itself wants undefined, so it is translated at the call.\n *\n * `--info` answers \"what is in this recording and what would converting it cost\", which\n * is exactly the question you want to ask across a directory of hundreds of recordings —\n * and the text table is the wrong shape for that. `--json` previously applied only to\n * conversions, so scripts had to parse the aligned columns or convert files just to learn\n * what was in them.\n *\n * Field names match `metadata.json` where the two describe the same thing, so a survey and\n * a conversion can be read by the same code.\n */\nexport function infoJson(file: EdfFile, plan: ConversionPlan, indent: number | null = 2): string {\n  const { header } = file;\n  const fileFor = new Map<number, string>();\n  for (const group of plan.groups) {\n    for (const channel of group.channels) fileFor.set(channel.signal.index, group.fileName);\n  }\n\n  return JSON.stringify(\n    {\n      path: file.path,\n      bytes: file.fileSize,\n      format: describeFormat(header),\n      start_datetime_local: formatWallClock(header.startDateTime),\n      start_date_raw: header.startDateRaw,\n      start_time_raw: header.startTimeRaw,\n      patient_id: header.patientId,\n      recording_id: header.recordingId,\n      data_records: file.recordCount,\n      data_records_declared: header.declaredRecordCount,\n      record_duration_seconds: header.recordDuration,\n      duration_seconds: file.durationSeconds,\n      // For a discontinuous file this exceeds duration_seconds by the length of the gaps.\n      time_span_seconds: plan.range.recordingEndSeconds - plan.range.recordingStartSeconds,\n      annotation_channels: file.annotationSignals.length,\n      channels: file.dataSignals.map((signal) => ({\n        signal_index: signal.index,\n        column: plan.columnNames.get(signal.index) ?? '',\n        label: signal.label,\n        unit: signal.physicalDimension,\n        sampling_rate_hz: signal.samplingRate,\n        samples_per_record: signal.samplesPerRecord,\n        physical_min: signal.physicalMin,\n        physical_max: signal.physicalMax,\n        digital_min: signal.digitalMin,\n        digital_max: signal.digitalMax,\n        transducer: signal.transducer,\n        prefiltering: signal.prefiltering,\n        output_file: fileFor.get(signal.index) ?? null,\n      })),\n      estimate: {\n        rows: plan.estimate.rows,\n        // Character count of the CSV. With --gzip the file on disk is smaller than this.\n        bytes: plan.estimate.bytes,\n        exceeds_spreadsheet_limit: plan.estimate.exceedsSpreadsheetLimit,\n      },\n      // The plan's mixed-rate warning replaces the header parser's, as it does everywhere\n      // else. This was the one consumer left out of that when 0.3.2 made the warning follow\n      // --channels, so `--info --json` carried it twice: once counting the rates being\n      // converted and once counting every rate in the file, with the same code and severity.\n      warnings: plan.diagnostics\n        .concat(withoutFileRateWarning(file.diagnostics))\n        .map((d) => ({ code: d.code, severity: d.severity, message: d.message })),\n    },\n    null,\n    indent ?? undefined,\n  );\n}\n\n/** One line per diagnostic, prefixed so warnings are greppable. */\nexport function formatDiagnostics(diagnostics: readonly Diagnostic[]): string {\n  return diagnostics\n    .map((d) => {\n      // Diagnostics quote channel labels, which come from the file, so they need the\n      // same treatment as the --info table.\n      const head = `${d.severity === 'warning' ? 'warning' : 'note'}: ${printable(d.message)}`;\n      return d.hint ? `${head}\\n         ${printable(d.hint)}` : head;\n    })\n    .join('\\n');\n}\n\nexport function formatSummary(result: ConvertResult): string {\n  const lines: string[] = [];\n  const rows: string[][] = [];\n  for (const file of result.files) {\n    // `.csv.gz` is still a CSV, and its rows are still rows. The suffix test dropped the\n    // unit from every line of a --gzip summary, so the numbers stood on their own.\n    rows.push([\n      `  ${file.name}`,\n      file.rows.toLocaleString('en-US'),\n      /\\.csv(\\.gz)?$/u.test(file.name) ? 'rows' : '',\n    ]);\n  }\n  lines.push(`Wrote ${result.outputDir}`);\n  lines.push(table(rows, new Set([1])));\n  lines.push(`Done in ${(result.elapsedMs / 1000).toFixed(1)}s.`);\n  return lines.join('\\n');\n}\n\nexport function summaryJson(result: ConvertResult, indent: number | null = 2): string {\n  return JSON.stringify(\n    {\n      output_dir: result.outputDir,\n      files: result.files,\n      annotations: result.annotationCount,\n      duration_seconds: result.file.durationSeconds,\n      records: result.file.recordCount,\n      elapsed_ms: result.elapsedMs,\n      warnings: result.diagnostics.map((d) => ({ code: d.code, severity: d.severity, message: d.message })),\n    },\n    null,\n    indent ?? undefined,\n  );\n}\n"]}
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/cli/report.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,SAAS,KAAK,CAAC,IAAoC,EAAE,UAA+B;IAClF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YACtB,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACX,GAAG;SACA,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACf,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC;SACV,OAAO,EAAE,CACb;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,4CAA4C;IAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,gCAAgC,EAAE,CAAC,CAAC,EAAE,EAAE,CAC1D,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAM,GAAG,EAAE;IACtD,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;SACnE,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,IAAoB;IAC5D,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,cAAc,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CACR,cACE,eAAe,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC;QACxD,GAAG,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,gBACrE,EAAE,CACH,CAAC;IACF,KAAK,CAAC,IAAI,CACR,cAAc,cAAc,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,IAAI,CAAC,WAAW,eAAe,MAAM,CAAC,cAAc,IAAI,CACjH,CAAC;IACF,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACtF,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,IAAI,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,cAAc,cAAc,CAAC,WAAW,CAAC,8BAA8B,CAAC,CAAC;IACtF,CAAC;IACD;;;;;;;;;;;MAWE;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC;IAClD,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,EAAE,CAAC;QAC3D,oFAAoF;QACpF,qFAAqF;QACrF,2EAA2E;QAC3E,KAAK,CAAC,IAAI,CACR,cAAc,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,qDAAqD,CACvF,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACvD,IAAI,MAAM,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAElF,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,sFAAsF;IACtF,gFAAgF;IAChF,MAAM,eAAe,GAAG,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC;IACtD,MAAM,cAAc,GAClB,eAAe,GAAG,CAAC;QACjB,CAAC,CAAC,MAAM,eAAe,sBAAsB,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;QAC/E,CAAC,CAAC,EAAE,CAAC;IACT,KAAK,CAAC,IAAI,CACR,cAAc,OAAO,CAAC,MAAM,UAAU,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,cAAc,EAAE,CACzF,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,MAAM,IAAI,GAAe,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1F,CAAC;IACD,sFAAsF;IACtF,wFAAwF;IACxF,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3E,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC;YACR,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YACpB,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACnD,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC;YACvB,SAAS,CAAC,MAAM,CAAC,iBAAiB,CAAC;YACnC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK;YACrB,GAAG,MAAM,CAAC,WAAW,OAAO,MAAM,CAAC,WAAW,EAAE;YAChD;;;;;;cAME;YACF,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;gBACvB,CAAC,MAAM,CAAC,gBAAgB,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB,CAAC;SACtE,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,MAAM,KAAK,MAAM;YACpB,CAAC,CAAC,qFAAqF;gBACrF,2EAA2E;YAC7E,CAAC,CAAC,qDAAqD,IAAI,CAAC,MAAM,CAAC,MAAM,wBAAwB;gBAC/F,0BAA0B,CAC/B,CAAC;IACJ,CAAC;IACD;;;;;;;;;;;;MAYE;IACF;;;;;;;;MAQE;IACF,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnD,sFAAsF;QACtF,wEAAwE;QACxE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9C,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;YAC/B,CAAC,CAAC,0BAA0B,MAAM,gBAAgB,MAAM,4BAA4B;gBAClF,uDAAuD;YACzD,CAAC,CAAC,uBAAuB,MAAM,2CAA2C,MAAM,GAAG;gBACjF,yDAAyD,CAC9D,CAAC;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,uFAAuF;IACvF,yFAAyF;IACzF,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC;IAC9B,KAAK,CAAC,IAAI,CACR,eAAe,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,iBAAiB;QACxE,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,GAAG,CACpF,CAAC;IAEF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAa,EAAE,IAAoB,EAAE,SAAwB,CAAC;IACrF,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1F,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,QAAQ;QACpB,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;QAC9B,oBAAoB,EAAE,eAAe,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3D,cAAc,EAAE,MAAM,CAAC,YAAY;QACnC,cAAc,EAAE,MAAM,CAAC,YAAY;QACnC,UAAU,EAAE,MAAM,CAAC,SAAS;QAC5B,YAAY,EAAE,MAAM,CAAC,WAAW;QAChC,YAAY,EAAE,IAAI,CAAC,WAAW;QAC9B,qBAAqB,EAAE,MAAM,CAAC,mBAAmB;QACjD,uBAAuB,EAAE,MAAM,CAAC,cAAc;QAC9C,gBAAgB,EAAE,IAAI,CAAC,eAAe;QACtC,oFAAoF;QACpF,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB;QACpF,uFAAuF;QACvF,uFAAuF;QACvF,2EAA2E;QAC3E,oBAAoB,EAAE,IAAI,CAAC,KAAK,CAAC,qBAAqB;QACtD,mBAAmB,EAAE,IAAI,CAAC,iBAAiB,CAAC,MAAM;QAClD,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,YAAY,EAAE,MAAM,CAAC,KAAK;YAC1B,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE;YAChD,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,IAAI,EAAE,MAAM,CAAC,iBAAiB;YAC9B,gBAAgB,EAAE,MAAM,CAAC,YAAY;YACrC,kBAAkB,EAAE,MAAM,CAAC,gBAAgB;YAC3C,YAAY,EAAE,MAAM,CAAC,WAAW;YAChC,YAAY,EAAE,MAAM,CAAC,WAAW;YAChC,WAAW,EAAE,MAAM,CAAC,UAAU;YAC9B,WAAW,EAAE,MAAM,CAAC,UAAU;YAC9B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI;SAC/C,CAAC,CAAC;QACH,QAAQ,EAAE;YACR,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;YACxB,iFAAiF;YACjF,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK;YAC1B,yBAAyB,EAAE,IAAI,CAAC,QAAQ,CAAC,uBAAuB;SACjE;QACD,oFAAoF;QACpF,sFAAsF;QACtF,iFAAiF;QACjF,uFAAuF;QACvF,QAAQ,EAAE,IAAI,CAAC,WAAW;aACvB,MAAM,CAAC,sBAAsB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KAC5E,EACD,IAAI,EACJ,MAAM,IAAI,SAAS,CACpB,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,WAAkC;IAClE,OAAO,WAAW;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,+EAA+E;QAC/E,sCAAsC;QACtC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QACzF,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,cAAc,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAClE,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAChC,qFAAqF;QACrF,+EAA+E;QAC/E,IAAI,CAAC,IAAI,CAAC;YACR,KAAK,IAAI,CAAC,IAAI,EAAE;YAChB,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;YACjC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE;SAC/C,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAqB,EAAE,SAAwB,CAAC;IAC1E,OAAO,IAAI,CAAC,SAAS,CACnB;QACE,UAAU,EAAE,MAAM,CAAC,SAAS;QAC5B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,eAAe;QACnC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,eAAe;QAC7C,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW;QAChC,UAAU,EAAE,MAAM,CAAC,SAAS;QAC5B,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KACtG,EACD,IAAI,EACJ,MAAM,IAAI,SAAS,CACpB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Human-readable output for the terminal.\n *\n * Everything here is plain text with no colour codes, so piping to a file or a log\n * produces exactly what appeared on screen.\n */\n\nimport type { Diagnostic } from '../edf/errors.js';\nimport type { EdfFile } from '../edf/reader.js';\nimport { describeFormat, formatRates, formatWallClock } from '../edf/header.js';\nimport { formatBytes, formatDuration } from '../format/number.js';\nimport type { ConversionPlan } from '../convert/plan.js';\nimport { withoutFileRateWarning } from '../convert/plan.js';\nimport type { ConvertResult } from '../convert/run.js';\n\nfunction table(rows: readonly (readonly string[])[], alignRight: ReadonlySet<number>): string {\n  if (rows.length === 0) return '';\n  const width: number[] = [];\n  for (const row of rows) {\n    row.forEach((cell, i) => {\n      width[i] = Math.max(width[i] ?? 0, cell.length);\n    });\n  }\n  return rows\n    .map((row) =>\n      row\n        .map((cell, i) => {\n          const w = width[i] ?? 0;\n          return alignRight.has(i) ? cell.padStart(w) : cell.padEnd(w);\n        })\n        .join('  ')\n        .trimEnd(),\n    )\n    .join('\\n');\n}\n\n/**\n * Make header text safe to print to a terminal.\n *\n * EDF identification fields and channel labels are free text copied verbatim out of the\n * file, and `--info` puts them straight on stdout. A header carrying ANSI escapes could\n * therefore drive the reader's terminal — `\\x1b[2J\\x1b[H` clears the screen and homes the\n * cursor, which is enough to hide the rest of the output or repaint it as something else.\n * Nobody writes an EDF header that way on purpose, which is exactly why a file that does\n * should not be trusted with the terminal.\n *\n * Control bytes are shown as their escape instead, so a corrupt field stays diagnosable\n * rather than being silently swallowed. This affects display only: `channels.csv` and\n * `metadata.json` still copy the field verbatim, and CSV quoting already makes that safe.\n */\nexport function printable(text: string): string {\n  // eslint-disable-next-line no-control-regex\n  return text.replace(/[\\u0000-\\u001f\\u007f-\\u009f]/gu, (c) =>\n    `\\\\x${c.codePointAt(0)!.toString(16).padStart(2, '0')}`,\n  );\n}\n\n/**\n * The same protection for text that is meant to span lines.\n *\n * `printable` escapes newlines along with everything else, which is right for a channel\n * label — one has no business containing a line break, and it would break the `--info`\n * table's alignment. It is wrong for a whole message: several are written on two lines,\n * and Node's own option errors run to three. Escaping those turned the break into text:\n *\n *     error: No channel named \"ECQ\". Did you mean \"ECG\"?\\x0aRun with --info to list ...\n *\n * Each line is escaped on its own, so nothing here gains the ability to drive a terminal.\n * A carriage return is still escaped, so no line can be repainted after it is printed —\n * which is the property that mattered. A newline can only add a line, never overwrite one.\n */\nexport function printableLines(text: string, indent = ''): string {\n  return text\n    .split('\\n')\n    .map((line, index) => (index === 0 ? '' : indent) + printable(line))\n    .join('\\n');\n}\n\n/** The `--info` view: what is in this recording, and what would converting it produce. */\nexport function formatInfo(file: EdfFile, plan: ConversionPlan): string {\n  const { header } = file;\n  const lines: string[] = [];\n\n  lines.push(`File       ${file.path}`);\n  lines.push(`Format     ${describeFormat(header)}`);\n  lines.push(\n    `Recorded   ${\n      formatWallClock(header.startDateTime)?.replace('T', ' ') ??\n      `${printable(header.startDateRaw)} ${printable(header.startTimeRaw)} (unparseable)`\n    }`,\n  );\n  lines.push(\n    `Duration   ${formatDuration(file.durationSeconds)}  (${file.recordCount} records of ${header.recordDuration}s)`,\n  );\n  const elapsedSpan = plan.range.recordingEndSeconds - plan.range.recordingStartSeconds;\n  if (Math.abs(elapsedSpan - file.durationSeconds) > 1e-9) {\n    lines.push(`Time span  ${formatDuration(elapsedSpan)}  (includes discontinuities)`);\n  }\n  /*\n    Where the samples begin, when that is not zero.\n\n    0.4.9 made the first record's timekeeping TAL the point a recording is timed from, so a\n    file whose TALs start at +1000 writes `time_s` from 1000.000 and takes `--start` and\n    `--end` on that same clock. None of that appeared here: the report said \"Duration 3s\",\n    which reads as 0 to 3, and `--start 0 --end 1` then selected nothing and answered with\n    \"The window is inside the recording but lands where there is no data ... Run with --info\n    to see where the records actually sit\" — pointing at this report, which was the one place\n    the number was missing. It is in `plan.range` already and governs the estimate printed\n    below; it was simply never shown.\n  */\n  const startsAt = plan.range.recordingStartSeconds;\n  if (Number.isFinite(startsAt) && Math.abs(startsAt) > 1e-9) {\n    // In seconds rather than through formatDuration, because this number is meant to be\n    // typed back in: `--start` takes `1000s`, and \"16m 40s\" is not something it accepts.\n    // It is also how the empty-window warning renders the window it was given.\n    lines.push(\n      `Timed from ${startsAt.toFixed(3)}s  (first sample; --start and --end use this clock)`,\n    );\n  }\n  lines.push(`Size       ${formatBytes(file.fileSize)}`);\n  if (header.patientId) lines.push(`Patient    ${printable(header.patientId)}`);\n  if (header.recordingId) lines.push(`Recording  ${printable(header.recordingId)}`);\n\n  const signals = file.dataSignals;\n  lines.push('');\n  // The signal count was pluralised but the annotation-channel count was not, so a file\n  // carrying two of them read \"2 annotation channel\". EDF+ permits more than one.\n  const annotationCount = file.annotationSignals.length;\n  const annotationPart =\n    annotationCount > 0\n      ? ` + ${annotationCount} annotation channel${annotationCount === 1 ? '' : 's'}`\n      : '';\n  lines.push(\n    `Channels   ${signals.length} signal${signals.length === 1 ? '' : 's'}${annotationPart}`,\n  );\n  lines.push('');\n\n  const rows: string[][] = [['#', 'COLUMN', 'LABEL', 'UNIT', 'RATE', 'RANGE', 'OUTPUT']];\n  const fileFor = new Map<number, string>();\n  for (const group of plan.groups) {\n    for (const channel of group.channels) fileFor.set(channel.signal.index, group.fileName);\n  }\n  // Rendered as a group so that two channels recorded at different rates never show the\n  // same figure in the RATE column, which is the one thing this table is asked to settle.\n  const rateText = formatRates(signals.map((signal) => signal.samplingRate));\n  for (const [row, signal] of signals.entries()) {\n    rows.push([\n      String(signal.index),\n      printable(plan.columnNames.get(signal.index) ?? ''),\n      printable(signal.label),\n      printable(signal.physicalDimension),\n      `${rateText[row]} Hz`,\n      `${signal.physicalMin} to ${signal.physicalMax}`,\n      /*\n        A channel with no samples was reported as \"(not selected)\", which is a different\n        thing and not true when it was named on --channels. `edf2csv rec.edf --info\n        --channels unused` said the channel the command asked for had not been chosen, when\n        what is actually the case is that the file gives it nothing to convert. The\n        NO_SAMPLES warning below the table says so; the table contradicted it.\n      */\n      fileFor.get(signal.index) ??\n        (signal.samplesPerRecord === 0 ? '(no samples)' : '(not selected)'),\n    ]);\n  }\n  lines.push(table(rows, new Set([0])));\n\n  lines.push('');\n  if (plan.groups.length > 1) {\n    lines.push(\n      plan.layout === 'long'\n        ? `Sampling rates differ, and the long layout puts them in one table anyway: each row ` +\n          `carries its own time, so nothing has to line up. No channel is resampled.`\n        : `Sampling rates differ, so channels are written to ${plan.groups.length} files, one per rate. ` +\n          `No channel is resampled.`,\n    );\n  }\n  /*\n    The estimate describes the signal tables, and says so when that is not what will be\n    written.\n\n    Under --annotations-only there are no signal tables, and the line read \"Would write 0\n    rows, roughly 0 B.\" for a conversion that goes on to write annotations.csv with three\n    events in it. --info exists to say what a conversion will do; asserting it will write\n    nothing, when it will write a file, is the one thing it must not do.\n\n    How many events there are cannot be answered from the header — the annotation channel has\n    to be read record by record, which is the scan --info is for avoiding. So it says which\n    file, and that the count is not knowable this cheaply, rather than inventing a zero.\n  */\n  /*\n    No signal table to describe, whichever way that came about.\n\n    This asked only whether `--annotations-only` had been given. A recording that has no\n    signal channels — one holding nothing but EDF+ annotations — has none either, and fell\n    through to the estimate line: \"Would write 0 rows, roughly 0 B.\" for a conversion that\n    goes on to write an annotations.csv with events in it, beside channels.csv and\n    metadata.json. That is the sentence 0.4.51 removed, arriving by the other route.\n  */\n  if (!plan.writeSignals || plan.groups.length === 0) {\n    // Named as they will be written. --info is read to find out what a run leaves behind,\n    // and a script that opens the name it was given must find a file there.\n    const suffix = plan.gzip ? '.csv.gz' : '.csv';\n    lines.push(\n      file.annotationSignals.length > 0\n        ? `Would write annotations${suffix} and channels${suffix}, and no signal data. How ` +\n          'many events there are cannot be told from the header.'\n        : `Would write channels${suffix} and no signal data — and no annotations${suffix} ` +\n          'either, since this recording has no annotation channel.',\n    );\n    return lines.join('\\n');\n  }\n\n  // The estimate counts the characters of the CSV, which is what --gzip then compresses.\n  // Reporting it as the size on disk would overstate a compressed conversion several-fold.\n  const compressing = plan.gzip;\n  lines.push(\n    `Would write ${plan.estimate.rows.toLocaleString('en-US')} rows, roughly ` +\n      `${formatBytes(plan.estimate.bytes)}${compressing ? ' before compression' : ''}.`,\n  );\n\n  return lines.join('\\n');\n}\n\n/**\n * The `--info` view as JSON, for surveying files from a script.\n *\n * `indent` is 2 for a single recording, matching what this has always printed, and null for\n * a batch — several pretty-printed documents run together are readable by a streaming parser\n * but not by anything that expects one record per line, and a batch is exactly where\n * line-oriented reading is wanted. null rather than undefined because a default parameter\n * takes effect when undefined is passed, which quietly restored the indentation this was\n * meant to drop; JSON.stringify itself wants undefined, so it is translated at the call.\n *\n * `--info` answers \"what is in this recording and what would converting it cost\", which\n * is exactly the question you want to ask across a directory of hundreds of recordings —\n * and the text table is the wrong shape for that. `--json` previously applied only to\n * conversions, so scripts had to parse the aligned columns or convert files just to learn\n * what was in them.\n *\n * Field names match `metadata.json` where the two describe the same thing, so a survey and\n * a conversion can be read by the same code.\n */\nexport function infoJson(file: EdfFile, plan: ConversionPlan, indent: number | null = 2): string {\n  const { header } = file;\n  const fileFor = new Map<number, string>();\n  for (const group of plan.groups) {\n    for (const channel of group.channels) fileFor.set(channel.signal.index, group.fileName);\n  }\n\n  return JSON.stringify(\n    {\n      path: file.path,\n      bytes: file.fileSize,\n      format: describeFormat(header),\n      start_datetime_local: formatWallClock(header.startDateTime),\n      start_date_raw: header.startDateRaw,\n      start_time_raw: header.startTimeRaw,\n      patient_id: header.patientId,\n      recording_id: header.recordingId,\n      data_records: file.recordCount,\n      data_records_declared: header.declaredRecordCount,\n      record_duration_seconds: header.recordDuration,\n      duration_seconds: file.durationSeconds,\n      // For a discontinuous file this exceeds duration_seconds by the length of the gaps.\n      time_span_seconds: plan.range.recordingEndSeconds - plan.range.recordingStartSeconds,\n      // Where `time_s` begins, and the clock `--start` and `--end` are read against. Usually\n      // zero; not when the first record's timekeeping TAL puts the recording elsewhere. Both\n      // of the fields above are lengths and neither says where that length sits.\n      first_sample_seconds: plan.range.recordingStartSeconds,\n      annotation_channels: file.annotationSignals.length,\n      channels: file.dataSignals.map((signal) => ({\n        signal_index: signal.index,\n        column: plan.columnNames.get(signal.index) ?? '',\n        label: signal.label,\n        unit: signal.physicalDimension,\n        sampling_rate_hz: signal.samplingRate,\n        samples_per_record: signal.samplesPerRecord,\n        physical_min: signal.physicalMin,\n        physical_max: signal.physicalMax,\n        digital_min: signal.digitalMin,\n        digital_max: signal.digitalMax,\n        transducer: signal.transducer,\n        prefiltering: signal.prefiltering,\n        output_file: fileFor.get(signal.index) ?? null,\n      })),\n      estimate: {\n        rows: plan.estimate.rows,\n        // Character count of the CSV. With --gzip the file on disk is smaller than this.\n        bytes: plan.estimate.bytes,\n        exceeds_spreadsheet_limit: plan.estimate.exceedsSpreadsheetLimit,\n      },\n      // The plan's mixed-rate warning replaces the header parser's, as it does everywhere\n      // else. This was the one consumer left out of that when 0.3.2 made the warning follow\n      // --channels, so `--info --json` carried it twice: once counting the rates being\n      // converted and once counting every rate in the file, with the same code and severity.\n      warnings: plan.diagnostics\n        .concat(withoutFileRateWarning(file.diagnostics))\n        .map((d) => ({ code: d.code, severity: d.severity, message: d.message })),\n    },\n    null,\n    indent ?? undefined,\n  );\n}\n\n/** One line per diagnostic, prefixed so warnings are greppable. */\nexport function formatDiagnostics(diagnostics: readonly Diagnostic[]): string {\n  return diagnostics\n    .map((d) => {\n      // Diagnostics quote channel labels, which come from the file, so they need the\n      // same treatment as the --info table.\n      const head = `${d.severity === 'warning' ? 'warning' : 'note'}: ${printable(d.message)}`;\n      return d.hint ? `${head}\\n         ${printable(d.hint)}` : head;\n    })\n    .join('\\n');\n}\n\nexport function formatSummary(result: ConvertResult): string {\n  const lines: string[] = [];\n  const rows: string[][] = [];\n  for (const file of result.files) {\n    // `.csv.gz` is still a CSV, and its rows are still rows. The suffix test dropped the\n    // unit from every line of a --gzip summary, so the numbers stood on their own.\n    rows.push([\n      `  ${file.name}`,\n      file.rows.toLocaleString('en-US'),\n      /\\.csv(\\.gz)?$/u.test(file.name) ? 'rows' : '',\n    ]);\n  }\n  lines.push(`Wrote ${result.outputDir}`);\n  lines.push(table(rows, new Set([1])));\n  lines.push(`Done in ${(result.elapsedMs / 1000).toFixed(1)}s.`);\n  return lines.join('\\n');\n}\n\nexport function summaryJson(result: ConvertResult, indent: number | null = 2): string {\n  return JSON.stringify(\n    {\n      output_dir: result.outputDir,\n      files: result.files,\n      annotations: result.annotationCount,\n      duration_seconds: result.file.durationSeconds,\n      records: result.file.recordCount,\n      elapsed_ms: result.elapsedMs,\n      warnings: result.diagnostics.map((d) => ({ code: d.code, severity: d.severity, message: d.message })),\n    },\n    null,\n    indent ?? undefined,\n  );\n}\n"]}

package/dist/convert/timing.d.ts

@@ -7,6 +7,8 @@ export interface AnnotationTimingData {
     malformedTimekeeping?: number;
     /** Events kept whose stated duration could not be read. */
     unreadableDurations?: number;
+    /** Events kept whose stated duration read as a number below zero. */
+    negativeDurations?: number;
 }
 /**
  * Resolve the true start time of every data record.

package/dist/convert/timing.js

@@ -29,6 +29,27 @@ export function deriveRecordStarts(file, annotationData) {
       else about it is intact. The count is of rows in annotations.csv, since a TAL may carry
       several texts and each becomes a row with the same empty cell.
     */
+    /*
+      A length of time below zero.
+  
+      Exported as the file wrote it, because a zero this tool invented would be a number no
+      writer wrote. But every use of it goes quietly wrong: the recipe the documentation gives
+      for the samples an event covers is `onset_s + duration_s`, and a duration of -3 ends the
+      window three seconds before the event begins and selects nothing, with nothing raised
+      anywhere to say why.
+    */
+    const negativeDurations = annotationData.negativeDurations ?? 0;
+    if (negativeDurations > 0) {
+        const one = negativeDurations === 1;
+        diagnostics.push({
+            code: 'ANNOTATION_DECODE_FAILED',
+            severity: 'warning',
+            message: `${negativeDurations} annotation${one ? '' : 's'} state${one ? 's' : ''} a duration ` +
+                `below zero, which is not a length of time.`,
+            hint: 'The value is written to annotations.csv as the file gave it. Adding it to onset_s ' +
+                'ends the event before it starts, so check these rows before using the durations.',
+        });
+    }
     const unreadableDurations = annotationData.unreadableDurations ?? 0;
     if (unreadableDurations > 0) {
         const one = unreadableDurations === 1;

package/dist/convert/timing.js.map

@@ -1 +1 @@
-{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/convert/timing.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Diagnostic } from '../edf/errors.js';\nimport type { EdfFile } from '../edf/reader.js';\n\nexport interface AnnotationTimingData {\n  recordStarts: (number | null)[];\n  malformed: number;\n  /** Unreadable TALs in first position, which carry timing rather than an event. */\n  malformedTimekeeping?: number;\n  /** Events kept whose stated duration could not be read. */\n  unreadableDurations?: number;\n}\n\n/**\n * Resolve the true start time of every data record.\n *\n * Continuous recordings need no table because their record positions are\n * arithmetic. EDF+D recordings carry their positions in the annotation channel;\n * missing or malformed timekeeping entries are reported before falling back.\n */\nexport function deriveRecordStarts(\n  file: EdfFile,\n  annotationData: AnnotationTimingData,\n): { starts: Float64Array | null; diagnostics: Diagnostic[] } {\n  const diagnostics: Diagnostic[] = [];\n\n  if (annotationData.malformed > 0) {\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${annotationData.malformed} annotation entr${annotationData.malformed === 1 ? 'y was' : 'ies were'} ` +\n        `unreadable and could not be exported.`,\n      hint: 'The rest were exported normally. The file may have been written by a non-conforming tool.',\n    });\n  }\n\n  /*\n    An event that was exported, minus a field.\n\n    `duration_s` is empty in annotations.csv when the file stated no duration, which is what\n    the documentation says an empty cell means. A duration the file did state and this could\n    not read produced exactly the same empty cell, so an event written with a duration of\n    `abc` was exported as an event that never had one — the same row as its neighbour, and\n    nothing said a field had been dropped.\n\n    Not counted among the entries that \"could not be exported\": this one was, and everything\n    else about it is intact. The count is of rows in annotations.csv, since a TAL may carry\n    several texts and each becomes a row with the same empty cell.\n  */\n  const unreadableDurations = annotationData.unreadableDurations ?? 0;\n  if (unreadableDurations > 0) {\n    const one = unreadableDurations === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${unreadableDurations} annotation${one ? '' : 's'} state${one ? 's' : ''} a duration ` +\n        `that is not a number, so ${one ? 'its' : 'their'} duration_s cell is empty.`,\n      hint:\n        'The onset and the description were read normally. An empty duration_s otherwise ' +\n        'means the file stated no duration, so these rows cannot be told apart from those.',\n    });\n  }\n\n  /*\n    A timekeeping TAL is not an event, and saying it \"could not be exported\" describes the\n    wrong loss twice over.\n\n    These were counted among the annotations, so a file with one unreadable timekeeping TAL\n    and three good events announced \"1 annotation entry was unreadable and could not be\n    exported\" — while exporting all three. Nothing was missing from annotations.csv; what\n    went missing was a record's position in time, which the message never mentioned.\n  */\n  const lostTimekeeping = annotationData.malformedTimekeeping ?? 0;\n  // The EDF+D branch below raises its own, which names the records and is more specific.\n  // Saying both would report one problem twice.\n  if (lostTimekeeping > 0 && file.header.continuity !== 'EDF+D') {\n    const one = lostTimekeeping === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${lostTimekeeping} data record${one ? '' : 's'} carr${one ? 'ies' : 'y'} a timekeeping ` +\n        `annotation that could not be read, so ${one ? 'it does' : 'they do'} not say where in ` +\n        `time ${one ? 'it sits' : 'they sit'}.`,\n      hint:\n        'No event was lost — a timekeeping annotation states a record\\'s start time and is ' +\n        'never exported. Times are derived from the records that could be read.',\n    });\n  }\n\n  /*\n    A continuous recording's records are contiguous, but the first one need not sit at zero.\n\n    EDF+ puts the header's start time and every annotation onset on one origin, and says the\n    first data record's timekeeping TAL \"always starts with +0.X\", stating the fraction of a\n    second by which that record follows it. Ignoring that fraction timed the samples from 0\n    while the events kept their true onsets, so the two ended up on origins half a second\n    apart — an event at +0.75 in a 4 Hz recording whose first TAL reads +0.5 landed on sample\n    3 instead of sample 1. The same file marked EDF+D, byte-identical but for the reserved\n    field, placed it correctly, which is what gives the omission away.\n\n    Records stay contiguous, which is what continuous means: only the origin moves. A first\n    TAL of +0 needs no table at all, and that is nearly every file.\n  */\n  if (file.header.continuity !== 'EDF+D') {\n    if (file.header.continuity !== 'EDF+C') return { starts: null, diagnostics };\n\n    /*\n      The origin comes from whichever record first states one, not from record 0 alone.\n\n      Reading only `recordStarts[0]` meant a single unreadable timekeeping TAL threw the\n      origin away and timed the whole file from zero — while records 1 and 2, saying plainly\n      that they start at 1.5s and 2.5s, went unread. A recording whose records sit at 0.5s,\n      1.5s and 2.5s came out with every sample 0.5s earlier than the file states, against\n      annotation onsets that kept their true values. That is precisely the mismatch 0.4.9\n      fixed, arriving through the one hole left in it, and the byte-identical EDF+D twin\n      timed it correctly, which is what gives it away.\n\n      Continuity is what makes this recoverable: record i sits at `origin + i * duration`,\n      so any readable record determines the origin for all of them.\n    */\n    const origin = originOf(annotationData.recordStarts, file.header.recordDuration);\n    if (origin === null) return { starts: null, diagnostics };\n\n    const contiguous = new Float64Array(file.recordCount);\n    for (let i = 0; i < file.recordCount; i++) {\n      contiguous[i] = origin + i * file.header.recordDuration;\n    }\n\n    /*\n      A file marked continuous whose own records disagree about it.\n\n      Nothing looked at records past the first, so an EDF+C file whose records are in fact\n      spread out was timed as though they were contiguous and said nothing. The records are\n      being read here anyway, so the contradiction costs nothing to notice — and it is the\n      file, not the reader, that has to be wrong for this to fire.\n\n      Compared against what the file can express, not for equality. 0.4.41 asked whether the\n      two doubles were the same, which they are not: a recording of 0.1s records sitting at\n      0.1, 0.2, 0.3 ... is contiguous by construction, and 0.1 + 2 * 0.1 is\n      0.30000000000000004. Two of its eight records were reported as contradicting\n      continuity, on an ordinary file — and under --strict that was a failed run. The\n      smallest interval the recording distinguishes is one sample of its fastest channel;\n      anything below half of that is arithmetic, not a gap. `canCarry` has already refused\n      origins where the double spacing swamps that interval, so the representation error is\n      under the tolerance by construction rather than by hope.\n    */\n    const tolerance = finestInterval(file) / 2;\n    const contradicting = annotationData.recordStarts.filter(\n      (declared, i) =>\n        typeof declared === 'number' && Math.abs(declared - (contiguous[i] as number)) > tolerance,\n    ).length;\n    if (contradicting > 0) {\n      diagnostics.push({\n        code: 'DISCONTINUOUS',\n        severity: 'warning',\n        message:\n          `This file is marked continuous (EDF+C), but ${contradicting} of its ` +\n          `${file.recordCount} data records say they start somewhere other than where ` +\n          `continuity puts them.`,\n        hint:\n          'Times are written as if the records were contiguous, which is what EDF+C means. ' +\n          'If the recording really has gaps, the file should have been marked EDF+D.',\n      });\n    }\n    const first = origin;\n    const last = contiguous[file.recordCount - 1] ?? first;\n    if (!canCarry(last, file)) {\n      diagnostics.push(unusableOrigin(first, file));\n      return { starts: null, diagnostics };\n    }\n    /*\n      An origin of zero is the same as no origin, for timing. It is not the same for the\n      check above.\n\n      This returned early on `origin === 0`, which is right about the times — contiguous\n      starts from zero are what timing from zero already produces — and skipped the\n      contradiction check on the way past. So an EDF+C file whose records say 0, 5 and 10 on\n      one-second records went unreported, while the same file shifted one second, saying 1, 6\n      and 11, was reported. The contradiction is in records 1 and 2 either way; where record 0\n      happens to sit decides nothing about it.\n    */\n    if (origin === 0) return { starts: null, diagnostics };\n    return { starts: contiguous, diagnostics };\n  }\n\n  if (file.annotationSignals.length === 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        'This file is marked discontinuous but has no annotation channel, so where its ' +\n        'records sit in time is not recorded anywhere.',\n      hint: 'Times are written as if the records were contiguous. Any gaps are lost.',\n    });\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    A record with no readable time is placed from the origin the other records establish,\n    not from zero.\n\n    `i * recordDuration` assumed the recording began at zero, which is the one thing the\n    other records are in a position to contradict: a file starting at 0.5s put its\n    unreadable record at 0.000 while its neighbours sat at 1.5s and 2.5s. The guess is still\n    a guess — a discontinuous file may have a gap exactly there — and it is still reported\n    below, but starting it from where the recording actually begins is strictly closer, and\n    it makes an EDF+D file agree with its byte-identical EDF+C twin about record 0.\n  */\n  const base = originOf(annotationData.recordStarts, file.header.recordDuration) ?? 0;\n  const starts = new Float64Array(file.recordCount);\n  const missing: number[] = [];\n  for (let i = 0; i < file.recordCount; i++) {\n    const declared = annotationData.recordStarts[i];\n    if (declared === null || declared === undefined) {\n      missing.push(i);\n      starts[i] = base + i * file.header.recordDuration;\n    } else {\n      starts[i] = declared;\n    }\n  }\n\n  if (missing.length > 0) {\n    const shown = missing.slice(0, 5).join(', ');\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${missing.length} of ${file.recordCount} data records carry no readable timekeeping ` +\n        `annotation (record${missing.length === 1 ? '' : 's'} ${shown}` +\n        `${missing.length > 5 ? ', …' : ''}), so their true position in time is unknown.`,\n      hint: 'Those records are timed as if they were contiguous; treat their timestamps as unreliable.',\n    });\n  }\n\n  /*\n    Furthest from zero, in either direction.\n\n    This took the signed maximum and seeded it with 0, so a recording whose records all sit\n    at negative onsets never got past the seed: `furthest` stayed 0, which any interval can\n    carry. Then the samples collapsed anyway, because the arithmetic that defeats a large\n    positive origin defeats a large negative one identically — at -1e16 seconds, adding a\n    1-second sample interval leaves the double unchanged.\n\n    A four-record recording of eight samples wrote two rows, exit 0, no warning. Its\n    byte-for-byte positive mirror wrote all eight and explained why it had to time them from\n    zero. Same file, same failure, opposite sign, opposite outcome — and the silent one is\n    the one that loses data, which is exactly what unusableOrigin exists to prevent.\n  */\n  let furthest = 0;\n  for (const start of starts) if (Math.abs(start) > Math.abs(furthest)) furthest = start;\n  if (!canCarry(furthest, file)) {\n    diagnostics.push(unusableOrigin(furthest, file));\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    Two ways a record can put the time column out of order, and only one was being looked for.\n\n    A record starting before the one before it is the obvious case. The other is a record\n    starting before the one before it *ends*: starts of 0, 0.5 and 1.0 on one-second records\n    are strictly increasing, so nothing fired, and the rows still came out 0.25, 0.5, 0.75,\n    0.5 — because record 0's samples run to 0.75 while record 1 begins at 0.5. Overlapping\n    acquisition is what a device does when it re-sends a buffer, and the reader has no more\n    to say about it than about the reversed case: every sample is written, in file order,\n    with the time the file gives it.\n\n    Contiguity is not overlap. A continuous recording has `starts[i] === starts[i-1] +\n    duration` exactly, so the comparison is made strict by a fraction of the finest interval\n    the recording can express — the same measure the origin check uses.\n  */\n  const slack = finestInterval(file) / 2;\n  let outOfOrder = 0;\n  let overlapping = 0;\n  for (let i = 1; i < starts.length; i++) {\n    const previous = starts[i - 1] as number;\n    const current = starts[i] as number;\n    if (current < previous) outOfOrder++;\n    else if (current + slack < previous + file.header.recordDuration) overlapping++;\n  }\n  if (outOfOrder > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message: `${outOfOrder} data record${outOfOrder === 1 ? '' : 's'} start earlier than the record before it.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n  if (overlapping > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        `${overlapping} data record${overlapping === 1 ? '' : 's'} start before the record ` +\n        `before ${overlapping === 1 ? 'it' : 'them'} ends, so their samples overlap in time.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n\n  return { starts, diagnostics };\n}\n\n/**\n * The recording's origin, from the first record that states where it is.\n *\n * Records of a continuous recording sit end to end, so record `i` beginning at `t` puts the\n * origin at `t - i * duration`. Any one readable timekeeping TAL is therefore enough, which\n * is what stops one unreadable entry from costing the whole file its position in time.\n */\nfunction originOf(recordStarts: readonly (number | null)[], recordDuration: number): number | null {\n  for (const [index, declared] of recordStarts.entries()) {\n    if (typeof declared !== 'number') continue;\n    const origin = declared - index * recordDuration;\n    return Number.isFinite(origin) ? origin : null;\n  }\n  return null;\n}\n\n/**\n * Whether times this far out can still tell one sample from the next.\n *\n * A double spaces its values further apart the larger they get: at 1e16 the gap is 2\n * seconds, so `t + 1` is `t`. Past that point a recording's declared origin stops being a\n * position and becomes a wall — the arithmetic that places records and samples returns the\n * origin itself, whatever is added to it.\n *\n * The finest thing that has to survive is the gap between two consecutive samples of the\n * fastest channel, since that is what the time column is made of. If that survives, so does\n * a whole record.\n */\nfunction canCarry(origin: number, file: EdfFile): boolean {\n  if (!Number.isFinite(origin)) return false;\n  // Asked of the origin furthest from zero, whichever side it is on: the spacing of doubles\n  // grows with magnitude, not with value, so -1e16 and +1e16 fail this identically.\n  return origin + finestInterval(file) > origin;\n}\n\n/**\n * The shortest span this recording can tell apart: one sample of its fastest channel.\n *\n * The time column is made of these, so nothing below one is a distinction the file is in a\n * position to make — which is what makes it the right size for both the \"can this origin\n * still separate two samples\" question and the \"is this record really somewhere else\"\n * question.\n */\nfunction finestInterval(file: EdfFile): number {\n  let interval = file.header.recordDuration;\n  for (const signal of file.header.signals) {\n    if (signal.isAnnotations || !(signal.samplesPerRecord > 0)) continue;\n    const step = file.header.recordDuration / signal.samplesPerRecord;\n    if (step > 0 && step < interval) interval = step;\n  }\n  return interval;\n}\n\n/**\n * An origin the file's own arithmetic cannot express, reported rather than acted on.\n *\n * Two things went wrong when this was taken at face value, both of them quiet. A file whose\n * records all collapsed onto one instant made the recording zero seconds long, and the\n * window resolver — which had no reason to suspect the recording rather than the request —\n * blamed a flag nobody had passed:\n *\n *     error: --start 100000000000000000s is at or past the end of this\n *            100000000000000000s recording.\n *\n * Slightly below that, the collapse is partial: `records[i].start + recordDuration` equals\n * the start again, so the test for \"does this record overlap the window\" fails for every\n * record whose neighbour rounded onto it. A twelve-row recording wrote four rows, exit 0,\n * no warning — the eight that vanished looked exactly like a file that never had them.\n *\n * Timing from zero is what the file did before 0.4.9 taught it to honour the first\n * timekeeping TAL, and at this magnitude it is the only column that can hold distinct\n * values. The origin is lost, so this says so.\n */\nfunction unusableOrigin(origin: number, file: EdfFile): Diagnostic {\n  return {\n    code: 'DISCONTINUOUS',\n    severity: 'warning',\n    message:\n      `This recording's timekeeping annotations place it ${origin}s from its own start ` +\n      `date, which is too far out for its ${file.header.recordDuration}s records to be told ` +\n      `apart: at that magnitude adding a sample interval leaves the number unchanged.`,\n    hint:\n      'Sample times are written from zero instead, so every row is present and the column ' +\n      'increases. Add the onsets in annotations.csv to recover absolute times if you need them.',\n  };\n}\n"]}
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/convert/timing.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Diagnostic } from '../edf/errors.js';\nimport type { EdfFile } from '../edf/reader.js';\n\nexport interface AnnotationTimingData {\n  recordStarts: (number | null)[];\n  malformed: number;\n  /** Unreadable TALs in first position, which carry timing rather than an event. */\n  malformedTimekeeping?: number;\n  /** Events kept whose stated duration could not be read. */\n  unreadableDurations?: number;\n  /** Events kept whose stated duration read as a number below zero. */\n  negativeDurations?: number;\n}\n\n/**\n * Resolve the true start time of every data record.\n *\n * Continuous recordings need no table because their record positions are\n * arithmetic. EDF+D recordings carry their positions in the annotation channel;\n * missing or malformed timekeeping entries are reported before falling back.\n */\nexport function deriveRecordStarts(\n  file: EdfFile,\n  annotationData: AnnotationTimingData,\n): { starts: Float64Array | null; diagnostics: Diagnostic[] } {\n  const diagnostics: Diagnostic[] = [];\n\n  if (annotationData.malformed > 0) {\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${annotationData.malformed} annotation entr${annotationData.malformed === 1 ? 'y was' : 'ies were'} ` +\n        `unreadable and could not be exported.`,\n      hint: 'The rest were exported normally. The file may have been written by a non-conforming tool.',\n    });\n  }\n\n  /*\n    An event that was exported, minus a field.\n\n    `duration_s` is empty in annotations.csv when the file stated no duration, which is what\n    the documentation says an empty cell means. A duration the file did state and this could\n    not read produced exactly the same empty cell, so an event written with a duration of\n    `abc` was exported as an event that never had one — the same row as its neighbour, and\n    nothing said a field had been dropped.\n\n    Not counted among the entries that \"could not be exported\": this one was, and everything\n    else about it is intact. The count is of rows in annotations.csv, since a TAL may carry\n    several texts and each becomes a row with the same empty cell.\n  */\n  /*\n    A length of time below zero.\n\n    Exported as the file wrote it, because a zero this tool invented would be a number no\n    writer wrote. But every use of it goes quietly wrong: the recipe the documentation gives\n    for the samples an event covers is `onset_s + duration_s`, and a duration of -3 ends the\n    window three seconds before the event begins and selects nothing, with nothing raised\n    anywhere to say why.\n  */\n  const negativeDurations = annotationData.negativeDurations ?? 0;\n  if (negativeDurations > 0) {\n    const one = negativeDurations === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${negativeDurations} annotation${one ? '' : 's'} state${one ? 's' : ''} a duration ` +\n        `below zero, which is not a length of time.`,\n      hint:\n        'The value is written to annotations.csv as the file gave it. Adding it to onset_s ' +\n        'ends the event before it starts, so check these rows before using the durations.',\n    });\n  }\n\n  const unreadableDurations = annotationData.unreadableDurations ?? 0;\n  if (unreadableDurations > 0) {\n    const one = unreadableDurations === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${unreadableDurations} annotation${one ? '' : 's'} state${one ? 's' : ''} a duration ` +\n        `that is not a number, so ${one ? 'its' : 'their'} duration_s cell is empty.`,\n      hint:\n        'The onset and the description were read normally. An empty duration_s otherwise ' +\n        'means the file stated no duration, so these rows cannot be told apart from those.',\n    });\n  }\n\n  /*\n    A timekeeping TAL is not an event, and saying it \"could not be exported\" describes the\n    wrong loss twice over.\n\n    These were counted among the annotations, so a file with one unreadable timekeeping TAL\n    and three good events announced \"1 annotation entry was unreadable and could not be\n    exported\" — while exporting all three. Nothing was missing from annotations.csv; what\n    went missing was a record's position in time, which the message never mentioned.\n  */\n  const lostTimekeeping = annotationData.malformedTimekeeping ?? 0;\n  // The EDF+D branch below raises its own, which names the records and is more specific.\n  // Saying both would report one problem twice.\n  if (lostTimekeeping > 0 && file.header.continuity !== 'EDF+D') {\n    const one = lostTimekeeping === 1;\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${lostTimekeeping} data record${one ? '' : 's'} carr${one ? 'ies' : 'y'} a timekeeping ` +\n        `annotation that could not be read, so ${one ? 'it does' : 'they do'} not say where in ` +\n        `time ${one ? 'it sits' : 'they sit'}.`,\n      hint:\n        'No event was lost — a timekeeping annotation states a record\\'s start time and is ' +\n        'never exported. Times are derived from the records that could be read.',\n    });\n  }\n\n  /*\n    A continuous recording's records are contiguous, but the first one need not sit at zero.\n\n    EDF+ puts the header's start time and every annotation onset on one origin, and says the\n    first data record's timekeeping TAL \"always starts with +0.X\", stating the fraction of a\n    second by which that record follows it. Ignoring that fraction timed the samples from 0\n    while the events kept their true onsets, so the two ended up on origins half a second\n    apart — an event at +0.75 in a 4 Hz recording whose first TAL reads +0.5 landed on sample\n    3 instead of sample 1. The same file marked EDF+D, byte-identical but for the reserved\n    field, placed it correctly, which is what gives the omission away.\n\n    Records stay contiguous, which is what continuous means: only the origin moves. A first\n    TAL of +0 needs no table at all, and that is nearly every file.\n  */\n  if (file.header.continuity !== 'EDF+D') {\n    if (file.header.continuity !== 'EDF+C') return { starts: null, diagnostics };\n\n    /*\n      The origin comes from whichever record first states one, not from record 0 alone.\n\n      Reading only `recordStarts[0]` meant a single unreadable timekeeping TAL threw the\n      origin away and timed the whole file from zero — while records 1 and 2, saying plainly\n      that they start at 1.5s and 2.5s, went unread. A recording whose records sit at 0.5s,\n      1.5s and 2.5s came out with every sample 0.5s earlier than the file states, against\n      annotation onsets that kept their true values. That is precisely the mismatch 0.4.9\n      fixed, arriving through the one hole left in it, and the byte-identical EDF+D twin\n      timed it correctly, which is what gives it away.\n\n      Continuity is what makes this recoverable: record i sits at `origin + i * duration`,\n      so any readable record determines the origin for all of them.\n    */\n    const origin = originOf(annotationData.recordStarts, file.header.recordDuration);\n    if (origin === null) return { starts: null, diagnostics };\n\n    const contiguous = new Float64Array(file.recordCount);\n    for (let i = 0; i < file.recordCount; i++) {\n      contiguous[i] = origin + i * file.header.recordDuration;\n    }\n\n    /*\n      A file marked continuous whose own records disagree about it.\n\n      Nothing looked at records past the first, so an EDF+C file whose records are in fact\n      spread out was timed as though they were contiguous and said nothing. The records are\n      being read here anyway, so the contradiction costs nothing to notice — and it is the\n      file, not the reader, that has to be wrong for this to fire.\n\n      Compared against what the file can express, not for equality. 0.4.41 asked whether the\n      two doubles were the same, which they are not: a recording of 0.1s records sitting at\n      0.1, 0.2, 0.3 ... is contiguous by construction, and 0.1 + 2 * 0.1 is\n      0.30000000000000004. Two of its eight records were reported as contradicting\n      continuity, on an ordinary file — and under --strict that was a failed run. The\n      smallest interval the recording distinguishes is one sample of its fastest channel;\n      anything below half of that is arithmetic, not a gap. `canCarry` has already refused\n      origins where the double spacing swamps that interval, so the representation error is\n      under the tolerance by construction rather than by hope.\n    */\n    const tolerance = finestInterval(file) / 2;\n    const contradicting = annotationData.recordStarts.filter(\n      (declared, i) =>\n        typeof declared === 'number' && Math.abs(declared - (contiguous[i] as number)) > tolerance,\n    ).length;\n    if (contradicting > 0) {\n      diagnostics.push({\n        code: 'DISCONTINUOUS',\n        severity: 'warning',\n        message:\n          `This file is marked continuous (EDF+C), but ${contradicting} of its ` +\n          `${file.recordCount} data records say they start somewhere other than where ` +\n          `continuity puts them.`,\n        hint:\n          'Times are written as if the records were contiguous, which is what EDF+C means. ' +\n          'If the recording really has gaps, the file should have been marked EDF+D.',\n      });\n    }\n    const first = origin;\n    const last = contiguous[file.recordCount - 1] ?? first;\n    if (!canCarry(last, file)) {\n      diagnostics.push(unusableOrigin(first, file));\n      return { starts: null, diagnostics };\n    }\n    /*\n      An origin of zero is the same as no origin, for timing. It is not the same for the\n      check above.\n\n      This returned early on `origin === 0`, which is right about the times — contiguous\n      starts from zero are what timing from zero already produces — and skipped the\n      contradiction check on the way past. So an EDF+C file whose records say 0, 5 and 10 on\n      one-second records went unreported, while the same file shifted one second, saying 1, 6\n      and 11, was reported. The contradiction is in records 1 and 2 either way; where record 0\n      happens to sit decides nothing about it.\n    */\n    if (origin === 0) return { starts: null, diagnostics };\n    return { starts: contiguous, diagnostics };\n  }\n\n  if (file.annotationSignals.length === 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        'This file is marked discontinuous but has no annotation channel, so where its ' +\n        'records sit in time is not recorded anywhere.',\n      hint: 'Times are written as if the records were contiguous. Any gaps are lost.',\n    });\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    A record with no readable time is placed from the origin the other records establish,\n    not from zero.\n\n    `i * recordDuration` assumed the recording began at zero, which is the one thing the\n    other records are in a position to contradict: a file starting at 0.5s put its\n    unreadable record at 0.000 while its neighbours sat at 1.5s and 2.5s. The guess is still\n    a guess — a discontinuous file may have a gap exactly there — and it is still reported\n    below, but starting it from where the recording actually begins is strictly closer, and\n    it makes an EDF+D file agree with its byte-identical EDF+C twin about record 0.\n  */\n  const base = originOf(annotationData.recordStarts, file.header.recordDuration) ?? 0;\n  const starts = new Float64Array(file.recordCount);\n  const missing: number[] = [];\n  for (let i = 0; i < file.recordCount; i++) {\n    const declared = annotationData.recordStarts[i];\n    if (declared === null || declared === undefined) {\n      missing.push(i);\n      starts[i] = base + i * file.header.recordDuration;\n    } else {\n      starts[i] = declared;\n    }\n  }\n\n  if (missing.length > 0) {\n    const shown = missing.slice(0, 5).join(', ');\n    diagnostics.push({\n      code: 'ANNOTATION_DECODE_FAILED',\n      severity: 'warning',\n      message:\n        `${missing.length} of ${file.recordCount} data records carry no readable timekeeping ` +\n        `annotation (record${missing.length === 1 ? '' : 's'} ${shown}` +\n        `${missing.length > 5 ? ', …' : ''}), so their true position in time is unknown.`,\n      hint: 'Those records are timed as if they were contiguous; treat their timestamps as unreliable.',\n    });\n  }\n\n  /*\n    Furthest from zero, in either direction.\n\n    This took the signed maximum and seeded it with 0, so a recording whose records all sit\n    at negative onsets never got past the seed: `furthest` stayed 0, which any interval can\n    carry. Then the samples collapsed anyway, because the arithmetic that defeats a large\n    positive origin defeats a large negative one identically — at -1e16 seconds, adding a\n    1-second sample interval leaves the double unchanged.\n\n    A four-record recording of eight samples wrote two rows, exit 0, no warning. Its\n    byte-for-byte positive mirror wrote all eight and explained why it had to time them from\n    zero. Same file, same failure, opposite sign, opposite outcome — and the silent one is\n    the one that loses data, which is exactly what unusableOrigin exists to prevent.\n  */\n  let furthest = 0;\n  for (const start of starts) if (Math.abs(start) > Math.abs(furthest)) furthest = start;\n  if (!canCarry(furthest, file)) {\n    diagnostics.push(unusableOrigin(furthest, file));\n    return { starts: null, diagnostics };\n  }\n\n  /*\n    Two ways a record can put the time column out of order, and only one was being looked for.\n\n    A record starting before the one before it is the obvious case. The other is a record\n    starting before the one before it *ends*: starts of 0, 0.5 and 1.0 on one-second records\n    are strictly increasing, so nothing fired, and the rows still came out 0.25, 0.5, 0.75,\n    0.5 — because record 0's samples run to 0.75 while record 1 begins at 0.5. Overlapping\n    acquisition is what a device does when it re-sends a buffer, and the reader has no more\n    to say about it than about the reversed case: every sample is written, in file order,\n    with the time the file gives it.\n\n    Contiguity is not overlap. A continuous recording has `starts[i] === starts[i-1] +\n    duration` exactly, so the comparison is made strict by a fraction of the finest interval\n    the recording can express — the same measure the origin check uses.\n  */\n  const slack = finestInterval(file) / 2;\n  let outOfOrder = 0;\n  let overlapping = 0;\n  for (let i = 1; i < starts.length; i++) {\n    const previous = starts[i - 1] as number;\n    const current = starts[i] as number;\n    if (current < previous) outOfOrder++;\n    else if (current + slack < previous + file.header.recordDuration) overlapping++;\n  }\n  if (outOfOrder > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message: `${outOfOrder} data record${outOfOrder === 1 ? '' : 's'} start earlier than the record before it.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n  if (overlapping > 0) {\n    diagnostics.push({\n      code: 'DISCONTINUOUS',\n      severity: 'warning',\n      message:\n        `${overlapping} data record${overlapping === 1 ? '' : 's'} start before the record ` +\n        `before ${overlapping === 1 ? 'it' : 'them'} ends, so their samples overlap in time.`,\n      hint: 'Rows are written in file order, so the time column will not increase monotonically.',\n    });\n  }\n\n  return { starts, diagnostics };\n}\n\n/**\n * The recording's origin, from the first record that states where it is.\n *\n * Records of a continuous recording sit end to end, so record `i` beginning at `t` puts the\n * origin at `t - i * duration`. Any one readable timekeeping TAL is therefore enough, which\n * is what stops one unreadable entry from costing the whole file its position in time.\n */\nfunction originOf(recordStarts: readonly (number | null)[], recordDuration: number): number | null {\n  for (const [index, declared] of recordStarts.entries()) {\n    if (typeof declared !== 'number') continue;\n    const origin = declared - index * recordDuration;\n    return Number.isFinite(origin) ? origin : null;\n  }\n  return null;\n}\n\n/**\n * Whether times this far out can still tell one sample from the next.\n *\n * A double spaces its values further apart the larger they get: at 1e16 the gap is 2\n * seconds, so `t + 1` is `t`. Past that point a recording's declared origin stops being a\n * position and becomes a wall — the arithmetic that places records and samples returns the\n * origin itself, whatever is added to it.\n *\n * The finest thing that has to survive is the gap between two consecutive samples of the\n * fastest channel, since that is what the time column is made of. If that survives, so does\n * a whole record.\n */\nfunction canCarry(origin: number, file: EdfFile): boolean {\n  if (!Number.isFinite(origin)) return false;\n  // Asked of the origin furthest from zero, whichever side it is on: the spacing of doubles\n  // grows with magnitude, not with value, so -1e16 and +1e16 fail this identically.\n  return origin + finestInterval(file) > origin;\n}\n\n/**\n * The shortest span this recording can tell apart: one sample of its fastest channel.\n *\n * The time column is made of these, so nothing below one is a distinction the file is in a\n * position to make — which is what makes it the right size for both the \"can this origin\n * still separate two samples\" question and the \"is this record really somewhere else\"\n * question.\n */\nfunction finestInterval(file: EdfFile): number {\n  let interval = file.header.recordDuration;\n  for (const signal of file.header.signals) {\n    if (signal.isAnnotations || !(signal.samplesPerRecord > 0)) continue;\n    const step = file.header.recordDuration / signal.samplesPerRecord;\n    if (step > 0 && step < interval) interval = step;\n  }\n  return interval;\n}\n\n/**\n * An origin the file's own arithmetic cannot express, reported rather than acted on.\n *\n * Two things went wrong when this was taken at face value, both of them quiet. A file whose\n * records all collapsed onto one instant made the recording zero seconds long, and the\n * window resolver — which had no reason to suspect the recording rather than the request —\n * blamed a flag nobody had passed:\n *\n *     error: --start 100000000000000000s is at or past the end of this\n *            100000000000000000s recording.\n *\n * Slightly below that, the collapse is partial: `records[i].start + recordDuration` equals\n * the start again, so the test for \"does this record overlap the window\" fails for every\n * record whose neighbour rounded onto it. A twelve-row recording wrote four rows, exit 0,\n * no warning — the eight that vanished looked exactly like a file that never had them.\n *\n * Timing from zero is what the file did before 0.4.9 taught it to honour the first\n * timekeeping TAL, and at this magnitude it is the only column that can hold distinct\n * values. The origin is lost, so this says so.\n */\nfunction unusableOrigin(origin: number, file: EdfFile): Diagnostic {\n  return {\n    code: 'DISCONTINUOUS',\n    severity: 'warning',\n    message:\n      `This recording's timekeeping annotations place it ${origin}s from its own start ` +\n      `date, which is too far out for its ${file.header.recordDuration}s records to be told ` +\n      `apart: at that magnitude adding a sample interval leaves the number unchanged.`,\n    hint:\n      'Sample times are written from zero instead, so every row is present and the column ' +\n      'increases. Add the onsets in annotations.csv to recover absolute times if you need them.',\n  };\n}\n"]}

package/dist/edf/annotations.d.ts

@@ -47,6 +47,13 @@ export interface DecodedRecordAnnotations {
      * be exported" describes a loss that did not happen and hides the one that did.
      */
     unreadableDurations: number;
+    /**
+     * Events kept whose stated duration is a readable number below zero.
+     *
+     * Separate from the count above because the value survives: it is written to the CSV as
+     * the file gave it, and what is wrong with it is arithmetic rather than parsing.
+     */
+    negativeDurations: number;
 }
 /**
  * Decode one data record's annotation bytes.

package/dist/edf/annotations.js

@@ -32,6 +32,7 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
     let malformed = 0;
     let malformedTimekeeping = 0;
     let unreadableDurations = 0;
+    let negativeDurations = 0;
     let start = 0;
     for (let i = 0; i <= bytes.length; i++) {
         if (i !== bytes.length && bytes[i] !== TAL_END)
@@ -63,6 +64,7 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
                 for (const annotation of parsed.annotations)
                     annotations.push(annotation);
                 unreadableDurations += parsed.unreadableDurations;
+                negativeDurations += parsed.negativeDurations;
             }
             else {
                 /*
@@ -83,7 +85,14 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
         }
         start = i + 1;
     }
-    return { recordStart, annotations, malformed, malformedTimekeeping, unreadableDurations };
+    return {
+        recordStart,
+        annotations,
+        malformed,
+        malformedTimekeeping,
+        unreadableDurations,
+        negativeDurations,
+    };
 }
 function parseTal(chunk, recordIndex) {
     // The onset must be explicitly signed; anything else is not a TAL.
@@ -123,6 +132,17 @@ function parseTal(chunk, recordIndex) {
         else
             durationUnreadable = true;
     }
+    /*
+      A duration is a length of time, and a length below zero is not one.
+  
+      The value is kept and written as the file gave it — inventing a zero, or dropping it to
+      an empty cell, would put a number in annotations.csv that no writer wrote, which is the
+      one thing this tool does not do. But it is reported, because everything downstream
+      quietly does the wrong thing with it: the recipe this documentation gives for the samples
+      an event covers is `onset_s + duration_s`, which for a duration of -3 ends three seconds
+      before the event starts and selects nothing at all, with no error anywhere.
+    */
+    const durationNegative = duration !== null && duration < 0;
     const annotations = [];
     for (const raw of parts.slice(1)) {
         // A trailing separator yields an empty segment; a timekeeping TAL is all empty.
@@ -131,8 +151,13 @@ function parseTal(chunk, recordIndex) {
         annotations.push({ onset, duration, text: raw, recordIndex });
     }
     // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row
-    // of annotations.csv with the same empty cell in it.
-    return { onset, annotations, unreadableDurations: durationUnreadable ? annotations.length : 0 };
+    // of annotations.csv with the same cell in it.
+    return {
+        onset,
+        annotations,
+        unreadableDurations: durationUnreadable ? annotations.length : 0,
+        negativeDurations: durationNegative ? annotations.length : 0,
+    };
 }
 export { SEP_TEXT, SEP_DURATION, TAL_END };
 //# sourceMappingURL=annotations.js.map

package/dist/edf/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EDF+ annotation (TAL) decoding.\n *\n * The annotations channel stores UTF-8 text in place of samples. Its bytes are a\n * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest\n * of the channel NUL-padded:\n *\n *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>\n *\n * The first TAL of every data record must carry that record's start time and no\n * text; that is how an EDF+D file states where each record actually sits in time.\n *\n *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>\n */\n\nimport { decodeUtf8 } from './bytes.js';\n\nconst SEP_TEXT = 0x14; // separates onset/duration from text, and text from text\nconst SEP_DURATION = 0x15; // separates onset from duration\nconst TAL_END = 0x00;\n\nconst TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);\nconst DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);\n\nexport interface Annotation {\n  /** Seconds from the start of the recording. */\n  onset: number;\n  /**\n   * Seconds, or null when the TAL stated no duration that could be read.\n   *\n   * Null covers two cases the file distinguishes and this field does not: a TAL that omitted\n   * the duration, and a TAL that stated one which is not a number. They are told apart by\n   * `unreadableDurations`, which is what raises the warning; the value itself has nowhere\n   * honest to put \"the file said `abc`\".\n   */\n  duration: number | null;\n  text: string;\n  /** Index of the data record this annotation was stored in. */\n  recordIndex: number;\n}\n\nexport interface DecodedRecordAnnotations {\n  /** Record start time in seconds, from the leading timekeeping TAL. */\n  recordStart: number | null;\n  annotations: Annotation[];\n  /** Non-empty chunks that were not valid TALs, so the caller can report them. */\n  malformed: number;\n  /** Unreadable TALs in first position, which carry a record's start time, not an event. */\n  malformedTimekeeping: number;\n  /**\n   * Events kept whose stated duration could not be read.\n   *\n   * Counted apart again, for the same reason the two above are: the entry was exported and\n   * nothing about it is missing except the one field, so calling it an entry that \"could not\n   * be exported\" describes a loss that did not happen and hides the one that did.\n   */\n  unreadableDurations: number;\n}\n\n/**\n * Decode one data record's annotation bytes.\n *\n * Malformed TALs are skipped rather than thrown, because a single bad annotation\n * should not cost the user an entire conversion. The count of skipped chunks is\n * returned so the caller can tell the user rather than losing them in silence.\n */\nexport function decodeRecordAnnotations(\n  bytes: Uint8Array,\n  recordIndex: number,\n  carriesTimekeeping = true,\n): DecodedRecordAnnotations {\n  const annotations: Annotation[] = [];\n  let recordStart: number | null = null;\n  let isFirstTal = true;\n  let malformed = 0;\n  let malformedTimekeeping = 0;\n  let unreadableDurations = 0;\n\n  let start = 0;\n  for (let i = 0; i <= bytes.length; i++) {\n    if (i !== bytes.length && bytes[i] !== TAL_END) continue;\n\n    if (i > start) {\n      const chunk = bytes.subarray(start, i);\n      const parsed = parseTal(chunk, recordIndex);\n\n      // The timekeeping TAL is the one in first POSITION, whether or not it decodes.\n      // Clearing this flag only on a successful parse meant that an unreadable first TAL\n      // promoted the next ordinary annotation to timekeeping, and its onset silently\n      // became the record's start time — shifting every sample in that record. Leaving\n      // recordStart null instead is what the caller already handles, with a fallback\n      // timestamp and an ANNOTATION_DECODE_FAILED warning naming the record.\n      /*\n        Only one annotation channel carries a record's start time.\n\n        This flagged the first TAL of *every* annotation channel as timekeeping. In a second\n        channel the first TAL is an ordinary event — so when one failed to parse, the event\n        was dropped and counted as a lost timekeeping entry, which produced the warning\n        \"3 data records carry a timekeeping annotation that could not be read\" followed by\n        \"No event was lost\". Three events had been lost, and the timekeeping in that file was\n        perfectly readable. Both sentences false, about the same three records.\n      */\n      const isTimekeeping = isFirstTal && carriesTimekeeping;\n      isFirstTal = false;\n\n      if (parsed) {\n        if (isTimekeeping) recordStart = parsed.onset;\n        for (const annotation of parsed.annotations) annotations.push(annotation);\n        unreadableDurations += parsed.unreadableDurations;\n      } else {\n        /*\n          Counted apart from the events, because losing one is a different loss.\n\n          A timekeeping TAL is never exported — it says where the record sits, not what\n          happened — so counting it among the entries that \"could not be exported\" both\n          overstated what was lost from annotations.csv and said nothing about the thing that\n          actually went missing, which is a record's position in time. A file with one\n          unreadable timekeeping TAL and three perfectly good events reported \"1 annotation\n          entry was unreadable and could not be exported\" while exporting all three.\n        */\n        if (isTimekeeping) malformedTimekeeping++;\n        else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return { recordStart, annotations, malformed, malformedTimekeeping, unreadableDurations };\n}\n\ninterface ParsedTal {\n  onset: number;\n  annotations: Annotation[];\n  /** How many of those annotations carry a duration the file stated and this could not read. */\n  unreadableDurations: number;\n}\n\nfunction parseTal(chunk: Uint8Array, recordIndex: number): ParsedTal | null {\n  // The onset must be explicitly signed; anything else is not a TAL.\n  const first = chunk[0];\n  if (first !== 0x2b /* + */ && first !== 0x2d /* - */) return null;\n\n  const text = decodeUtf8(chunk);\n  const parts = text.split(TEXT_SEP_CHAR);\n  const head = parts[0] ?? '';\n\n  let onsetText = head;\n  let durationText: string | null = null;\n  const durationSep = head.indexOf(DURATION_SEP_CHAR);\n  if (durationSep >= 0) {\n    onsetText = head.slice(0, durationSep);\n    durationText = head.slice(durationSep + 1);\n  }\n\n  const onset = Number(onsetText);\n  if (!Number.isFinite(onset)) return null;\n\n  /*\n    A duration the file stated and this could not read is not the same as no duration.\n\n    Both came out as `null` and so as an empty `duration_s` cell, which the documentation\n    defines as meaning the file gave no duration — so an event whose duration was written as\n    `abc` was exported as an event with no duration, indistinguishable from one beside it\n    that genuinely had none, and nothing anywhere said a field had been dropped. The onset is\n    already held to this standard: one that is not a number costs the whole TAL and is\n    reported. A duration is one field of an otherwise readable event, so the event is kept —\n    but it is counted, and the run says so.\n  */\n  let duration: number | null = null;\n  let durationUnreadable = false;\n  if (durationText !== null && durationText !== '') {\n    const d = Number(durationText);\n    if (Number.isFinite(d)) duration = d;\n    else durationUnreadable = true;\n  }\n\n  const annotations: Annotation[] = [];\n  for (const raw of parts.slice(1)) {\n    // A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n    if (raw === '') continue;\n    annotations.push({ onset, duration, text: raw, recordIndex });\n  }\n\n  // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row\n  // of annotations.csv with the same empty cell in it.\n  return { onset, annotations, unreadableDurations: durationUnreadable ? annotations.length : 0 };\n}\n\nexport { SEP_TEXT, SEP_DURATION, TAL_END };\n"]}
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EDF+ annotation (TAL) decoding.\n *\n * The annotations channel stores UTF-8 text in place of samples. Its bytes are a\n * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest\n * of the channel NUL-padded:\n *\n *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>\n *\n * The first TAL of every data record must carry that record's start time and no\n * text; that is how an EDF+D file states where each record actually sits in time.\n *\n *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>\n */\n\nimport { decodeUtf8 } from './bytes.js';\n\nconst SEP_TEXT = 0x14; // separates onset/duration from text, and text from text\nconst SEP_DURATION = 0x15; // separates onset from duration\nconst TAL_END = 0x00;\n\nconst TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);\nconst DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);\n\nexport interface Annotation {\n  /** Seconds from the start of the recording. */\n  onset: number;\n  /**\n   * Seconds, or null when the TAL stated no duration that could be read.\n   *\n   * Null covers two cases the file distinguishes and this field does not: a TAL that omitted\n   * the duration, and a TAL that stated one which is not a number. They are told apart by\n   * `unreadableDurations`, which is what raises the warning; the value itself has nowhere\n   * honest to put \"the file said `abc`\".\n   */\n  duration: number | null;\n  text: string;\n  /** Index of the data record this annotation was stored in. */\n  recordIndex: number;\n}\n\nexport interface DecodedRecordAnnotations {\n  /** Record start time in seconds, from the leading timekeeping TAL. */\n  recordStart: number | null;\n  annotations: Annotation[];\n  /** Non-empty chunks that were not valid TALs, so the caller can report them. */\n  malformed: number;\n  /** Unreadable TALs in first position, which carry a record's start time, not an event. */\n  malformedTimekeeping: number;\n  /**\n   * Events kept whose stated duration could not be read.\n   *\n   * Counted apart again, for the same reason the two above are: the entry was exported and\n   * nothing about it is missing except the one field, so calling it an entry that \"could not\n   * be exported\" describes a loss that did not happen and hides the one that did.\n   */\n  unreadableDurations: number;\n  /**\n   * Events kept whose stated duration is a readable number below zero.\n   *\n   * Separate from the count above because the value survives: it is written to the CSV as\n   * the file gave it, and what is wrong with it is arithmetic rather than parsing.\n   */\n  negativeDurations: number;\n}\n\n/**\n * Decode one data record's annotation bytes.\n *\n * Malformed TALs are skipped rather than thrown, because a single bad annotation\n * should not cost the user an entire conversion. The count of skipped chunks is\n * returned so the caller can tell the user rather than losing them in silence.\n */\nexport function decodeRecordAnnotations(\n  bytes: Uint8Array,\n  recordIndex: number,\n  carriesTimekeeping = true,\n): DecodedRecordAnnotations {\n  const annotations: Annotation[] = [];\n  let recordStart: number | null = null;\n  let isFirstTal = true;\n  let malformed = 0;\n  let malformedTimekeeping = 0;\n  let unreadableDurations = 0;\n  let negativeDurations = 0;\n\n  let start = 0;\n  for (let i = 0; i <= bytes.length; i++) {\n    if (i !== bytes.length && bytes[i] !== TAL_END) continue;\n\n    if (i > start) {\n      const chunk = bytes.subarray(start, i);\n      const parsed = parseTal(chunk, recordIndex);\n\n      // The timekeeping TAL is the one in first POSITION, whether or not it decodes.\n      // Clearing this flag only on a successful parse meant that an unreadable first TAL\n      // promoted the next ordinary annotation to timekeeping, and its onset silently\n      // became the record's start time — shifting every sample in that record. Leaving\n      // recordStart null instead is what the caller already handles, with a fallback\n      // timestamp and an ANNOTATION_DECODE_FAILED warning naming the record.\n      /*\n        Only one annotation channel carries a record's start time.\n\n        This flagged the first TAL of *every* annotation channel as timekeeping. In a second\n        channel the first TAL is an ordinary event — so when one failed to parse, the event\n        was dropped and counted as a lost timekeeping entry, which produced the warning\n        \"3 data records carry a timekeeping annotation that could not be read\" followed by\n        \"No event was lost\". Three events had been lost, and the timekeeping in that file was\n        perfectly readable. Both sentences false, about the same three records.\n      */\n      const isTimekeeping = isFirstTal && carriesTimekeeping;\n      isFirstTal = false;\n\n      if (parsed) {\n        if (isTimekeeping) recordStart = parsed.onset;\n        for (const annotation of parsed.annotations) annotations.push(annotation);\n        unreadableDurations += parsed.unreadableDurations;\n        negativeDurations += parsed.negativeDurations;\n      } else {\n        /*\n          Counted apart from the events, because losing one is a different loss.\n\n          A timekeeping TAL is never exported — it says where the record sits, not what\n          happened — so counting it among the entries that \"could not be exported\" both\n          overstated what was lost from annotations.csv and said nothing about the thing that\n          actually went missing, which is a record's position in time. A file with one\n          unreadable timekeeping TAL and three perfectly good events reported \"1 annotation\n          entry was unreadable and could not be exported\" while exporting all three.\n        */\n        if (isTimekeeping) malformedTimekeeping++;\n        else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return {\n    recordStart,\n    annotations,\n    malformed,\n    malformedTimekeeping,\n    unreadableDurations,\n    negativeDurations,\n  };\n}\n\ninterface ParsedTal {\n  onset: number;\n  annotations: Annotation[];\n  /** How many of those annotations carry a duration the file stated and this could not read. */\n  unreadableDurations: number;\n  /** How many carry a duration that read as a number below zero. */\n  negativeDurations: number;\n}\n\nfunction parseTal(chunk: Uint8Array, recordIndex: number): ParsedTal | null {\n  // The onset must be explicitly signed; anything else is not a TAL.\n  const first = chunk[0];\n  if (first !== 0x2b /* + */ && first !== 0x2d /* - */) return null;\n\n  const text = decodeUtf8(chunk);\n  const parts = text.split(TEXT_SEP_CHAR);\n  const head = parts[0] ?? '';\n\n  let onsetText = head;\n  let durationText: string | null = null;\n  const durationSep = head.indexOf(DURATION_SEP_CHAR);\n  if (durationSep >= 0) {\n    onsetText = head.slice(0, durationSep);\n    durationText = head.slice(durationSep + 1);\n  }\n\n  const onset = Number(onsetText);\n  if (!Number.isFinite(onset)) return null;\n\n  /*\n    A duration the file stated and this could not read is not the same as no duration.\n\n    Both came out as `null` and so as an empty `duration_s` cell, which the documentation\n    defines as meaning the file gave no duration — so an event whose duration was written as\n    `abc` was exported as an event with no duration, indistinguishable from one beside it\n    that genuinely had none, and nothing anywhere said a field had been dropped. The onset is\n    already held to this standard: one that is not a number costs the whole TAL and is\n    reported. A duration is one field of an otherwise readable event, so the event is kept —\n    but it is counted, and the run says so.\n  */\n  let duration: number | null = null;\n  let durationUnreadable = false;\n  if (durationText !== null && durationText !== '') {\n    const d = Number(durationText);\n    if (Number.isFinite(d)) duration = d;\n    else durationUnreadable = true;\n  }\n\n  /*\n    A duration is a length of time, and a length below zero is not one.\n\n    The value is kept and written as the file gave it — inventing a zero, or dropping it to\n    an empty cell, would put a number in annotations.csv that no writer wrote, which is the\n    one thing this tool does not do. But it is reported, because everything downstream\n    quietly does the wrong thing with it: the recipe this documentation gives for the samples\n    an event covers is `onset_s + duration_s`, which for a duration of -3 ends three seconds\n    before the event starts and selects nothing at all, with no error anywhere.\n  */\n  const durationNegative = duration !== null && duration < 0;\n\n  const annotations: Annotation[] = [];\n  for (const raw of parts.slice(1)) {\n    // A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n    if (raw === '') continue;\n    annotations.push({ onset, duration, text: raw, recordIndex });\n  }\n\n  // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row\n  // of annotations.csv with the same cell in it.\n  return {\n    onset,\n    annotations,\n    unreadableDurations: durationUnreadable ? annotations.length : 0,\n    negativeDurations: durationNegative ? annotations.length : 0,\n  };\n}\n\nexport { SEP_TEXT, SEP_DURATION, TAL_END };\n"]}

package/dist/edf/reader.d.ts

@@ -158,6 +158,8 @@ export declare class EdfFile {
         malformedTimekeeping: number;
         /** Events kept whose stated duration could not be read; see Annotation.duration. */
         unreadableDurations: number;
+        /** Events kept whose stated duration read as a number below zero. */
+        negativeDurations: number;
     }>;
     close(): Promise<void>;
 }

package/dist/edf/reader.js

@@ -362,9 +362,17 @@ export class EdfFile {
         let malformed = 0;
         let malformedTimekeeping = 0;
         let unreadableDurations = 0;
+        let negativeDurations = 0;
         const channels = this.annotationSignals;
         if (channels.length === 0) {
-            return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };
+            return {
+                annotations,
+                recordStarts,
+                malformed,
+                malformedTimekeeping,
+                unreadableDurations,
+                negativeDurations,
+            };
         }
         const { headerBytes, recordBytes, bytesPerSample } = this.header;
         const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));
@@ -388,10 +396,18 @@ export class EdfFile {
                 malformed += decoded.malformed;
                 malformedTimekeeping += decoded.malformedTimekeeping;
                 unreadableDurations += decoded.unreadableDurations;
+                negativeDurations += decoded.negativeDurations;
             }
         }
         annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);
-        return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };
+        return {
+            annotations,
+            recordStarts,
+            malformed,
+            malformedTimekeeping,
+            unreadableDurations,
+            negativeDurations,
+        };
     }
     async close() {
         if (this.#closed)

package/dist/edf/reader.js.map

@@ -1 +1 @@
-{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/edf/reader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Chunked reader for EDF / EDF+ files.\n *\n * Data records are read in batches sized by a byte budget rather than all at once,\n * so peak memory stays flat regardless of how long the recording is. A 4 GB file\n * and a 4 MB file use the same working set.\n */\n\nimport { open, stat } from 'node:fs/promises';\nimport type { FileHandle } from 'node:fs/promises';\n\nimport { createHash } from 'node:crypto';\n\nimport { EdfError } from './errors.js';\nimport type { Diagnostic } from './errors.js';\nimport { FIXED_HEADER_BYTES, SIGNAL_HEADER_BYTES, parseHeader, peekSignalCount } from './header.js';\nimport type { EdfHeader, EdfSignal } from './header.js';\nimport { decodeRecordAnnotations } from './annotations.js';\nimport type { Annotation } from './annotations.js';\nimport { decodeLatin1, readInt16LE } from './bytes.js';\n\n/**\n * How far `readOrigin` looks for a record that states its own start time.\n *\n * Enough that one or two unreadable timekeeping entries at the top of a file cost nothing,\n * few enough that `--info` stays a header read rather than a scan.\n */\nconst RECORDS_SEARCHED_FOR_ORIGIN = 16;\n\n/** Default read budget per batch. Large enough to amortise syscalls, small enough to stay cheap. */\nexport const DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;\n\nexport interface RecordBatch {\n  /** Index of the first record in this batch, relative to the whole file. */\n  firstRecordIndex: number;\n  recordCount: number;\n  /**\n   * Raw record bytes, `recordCount * header.recordBytes` long.\n   *\n   * The buffer is reused between iterations. Copy anything you need to keep past\n   * the current loop turn.\n   */\n  data: Uint8Array;\n}\n\nexport interface ReadRecordsOptions {\n  /** First record to read, inclusive. Defaults to 0. */\n  startRecord?: number;\n  /** Last record to read, exclusive. Defaults to the file's record count. */\n  endRecord?: number;\n  chunkBytes?: number;\n}\n\nexport class EdfFile {\n  readonly path: string;\n  readonly fileSize: number;\n  /**\n   * Last-modified time when this file was opened, in milliseconds, for the same reason as\n   * `fileSize`.\n   *\n   * Kept as the raw number rather than a Date because `new Date(ms).getTime()` truncates to\n   * whole milliseconds: comparing that against a later `fstat`, which carries the\n   * filesystem's sub-millisecond precision, reported every undisturbed conversion as one\n   * whose input had changed underneath it.\n   */\n  readonly modifiedAtOpenMs: number;\n  readonly header: EdfHeader;\n  /** Records actually present in the file, which may differ from the header's claim. */\n  readonly recordCount: number;\n  readonly trailingBytes: number;\n  readonly diagnostics: Diagnostic[];\n\n  #handle: FileHandle;\n  #closed = false;\n  /** The last answer `changedSinceOpen` computed, so it survives the file being closed. */\n  #changed: boolean | null = null;\n\n  private constructor(init: {\n    path: string;\n    fileSize: number;\n    modifiedAtOpenMs: number;\n    header: EdfHeader;\n    recordCount: number;\n    trailingBytes: number;\n    diagnostics: Diagnostic[];\n    handle: FileHandle;\n  }) {\n    this.path = init.path;\n    this.fileSize = init.fileSize;\n    this.modifiedAtOpenMs = init.modifiedAtOpenMs;\n    this.header = init.header;\n    this.recordCount = init.recordCount;\n    this.trailingBytes = init.trailingBytes;\n    this.diagnostics = init.diagnostics;\n    this.#handle = init.handle;\n  }\n\n  /**\n   * SHA-256 of the bytes this conversion actually read.\n   *\n   * Hashed through the open descriptor, over exactly the `fileSize` bytes that were there\n   * when the file was opened — the same number every record count and window in the output\n   * was derived from. Re-opening the path to hash it afterwards described whatever was at\n   * that name by then: a recording still being written grew from 2,000 records to 3,000\n   * mid-conversion and metadata.json recorded `data_records: 2000` beside the checksum and\n   * byte count of the 3,000-record file, which is provenance for bytes nobody converted.\n   * Replacing the file at that path did the same thing more completely.\n   */\n  async sha256(): Promise<string> {\n    this.#assertOpen();\n    const hash = createHash('sha256');\n    const buffer = Buffer.alloc(Math.min(this.fileSize, 4 * 1024 * 1024) || 1);\n    for (let at = 0; at < this.fileSize; ) {\n      const want = Math.min(buffer.length, this.fileSize - at);\n      const { bytesRead } = await this.#handle.read(buffer, 0, want, at);\n      if (bytesRead <= 0) {\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${this.fileSize} bytes to checksum but the file ended at ${at}; ` +\n            `it appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n      hash.update(buffer.subarray(0, bytesRead));\n      at += bytesRead;\n    }\n    return hash.digest('hex');\n  }\n\n  /**\n   * Whether the file has changed since it was opened, by size or by modification time.\n   *\n   * Checked through the descriptor, so it answers for the bytes that were read rather than\n   * for whatever now answers to the same name. A recording still being written is the\n   * ordinary cause, and the conversion is still correct for the data it saw — it is the\n   * claim that the output describes the file as it now stands that stops being true.\n   */\n  async changedSinceOpen(): Promise<boolean> {\n    /*\n      A closed file remembers its last answer rather than inventing a new one.\n\n      Returning false once closed asserted \"it did not change\", which is not something a\n      closed descriptor can know — and `convert()` closes the file before it returns, so\n      `result.file.changedSinceOpen()` denied the very change the INPUT_CHANGED diagnostic\n      in the same result object had just reported. One object, two answers.\n\n      `convert()` always asks before closing, so the cached answer is the true one. A caller\n      who closed the file without ever asking gets an error, which is the same treatment\n      every other method on a closed file gets.\n    */\n    if (this.#closed) {\n      if (this.#changed !== null) return this.#changed;\n      throw new EdfError(\n        'UNREADABLE',\n        `\"${this.path}\" is closed, and whether it changed while it was open was never checked.`,\n        'Ask before closing the file. A ConvertResult carries the answer already, since ' +\n          'convert() checks it on the way out.',\n      );\n    }\n    const now = await this.#handle.stat().catch(() => null);\n    if (now === null) return this.#changed ?? false;\n    this.#changed = now.size !== this.fileSize || now.mtimeMs !== this.modifiedAtOpenMs;\n    return this.#changed;\n  }\n\n  static async open(path: string): Promise<EdfFile> {\n    const info = await stat(path).catch((cause: unknown) => {\n      throw new EdfError('UNREADABLE', `Cannot read \"${path}\": ${describe(cause)}`);\n    });\n    if (info.isDirectory()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is a directory, not an EDF file.`);\n    }\n    if (!info.isFile()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is not a regular file.`);\n    }\n\n    const handle = await open(path, 'r');\n    try {\n      const fixed = Buffer.alloc(Math.min(FIXED_HEADER_BYTES, info.size));\n      if (fixed.length > 0) {\n        const bytesRead = await readFully(handle, fixed, 0, fixed.length, 0);\n        if (bytesRead < fixed.length) throw changedWhileReading(0, fixed.length, bytesRead);\n      }\n\n      // The signal count decides how much more header there is to read. Read by the header\n      // parser itself, so the two cannot disagree about which files are readable: this used\n      // to have its own Number(), which tolerated the NUL padding sloppy writers emit but\n      // not the comma decimal separator that COMMA_DECIMAL exists to accept.\n      let headerBuffer = fixed;\n      if (fixed.length === FIXED_HEADER_BYTES) {\n        const ns = peekSignalCount(fixed);\n        if (ns !== null) {\n          const total = FIXED_HEADER_BYTES + ns * SIGNAL_HEADER_BYTES;\n          if (total <= info.size) {\n            headerBuffer = Buffer.alloc(total);\n            const bytesRead = await readFully(handle, headerBuffer, 0, total, 0);\n            if (bytesRead < total) throw changedWhileReading(0, total, bytesRead);\n          }\n        }\n      }\n\n      const { header, recordCount, trailingBytes, diagnostics } = parseHeader(\n        headerBuffer,\n        info.size,\n      );\n\n      return new EdfFile({\n        path,\n        fileSize: info.size,\n        modifiedAtOpenMs: info.mtimeMs,\n        header,\n        recordCount,\n        trailingBytes,\n        diagnostics,\n        handle,\n      });\n    } catch (error) {\n      await handle.close().catch(() => {});\n      throw error;\n    }\n  }\n\n  /** Signal channels, excluding the EDF+ annotations channel. */\n  get dataSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => !s.isAnnotations);\n  }\n\n  /**\n   * The annotation channel a record's start time is read from.\n   *\n   * EDF+ puts the timekeeping TAL first in the first annotation channel, and this was read as\n   * `annotationSignals[0]` — the first one declared, whether or not it can hold anything. A\n   * writer that declares an annotation channel and gives it zero samples per record leaves a\n   * slot of zero bytes, so nothing was read from it, and the timekeeping in the channel after\n   * it went unread: a three-record EDF+D reported \"3 of 3 data records carry no readable\n   * timekeeping annotation\" about three that were perfectly readable, and timed the file from\n   * zero.\n   *\n   * A channel with no room carries nothing, so it is not the one the TAL is in.\n   */\n  get timekeepingSignal(): EdfSignal | undefined {\n    return this.annotationSignals.find((signal) => signal.samplesPerRecord > 0);\n  }\n\n  get annotationSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => s.isAnnotations);\n  }\n\n  /** Total recording duration in seconds, based on records actually present. */\n  get durationSeconds(): number {\n    return this.recordCount * this.header.recordDuration;\n  }\n\n  /** Read a half-open range of records in batches. */\n  async *readRecords(options: ReadRecordsOptions = {}): AsyncGenerator<RecordBatch> {\n    this.#assertOpen();\n\n    /*\n      Record bounds have to be whole records.\n\n      A fractional `startRecord` was carried straight into `position = headerBytes +\n      record * recordBytes`, so reading from 1.5 began half a record in and every sample\n      after it was decoded from the wrong offset: on the two-channel test fixture it\n      returned channel 2's values under channel 1's signal, with no error. Clamping\n      silently would be no better, since a caller asking for record 1.5 has a bug the\n      library should name rather than paper over.\n    */\n    for (const [name, value] of [\n      ['startRecord', options.startRecord],\n      ['endRecord', options.endRecord],\n    ] as const) {\n      if (value !== undefined && !Number.isInteger(value)) {\n        throw new EdfError(\n          'BAD_HEADER_FIELD',\n          `readRecords: ${name} must be a whole record index, got ${value}.`,\n          'Record boundaries are the unit the file can be read in; a fractional index would decode samples from the middle of a record.',\n        );\n      }\n    }\n\n    const start = Math.max(0, options.startRecord ?? 0);\n    const end = Math.min(this.recordCount, options.endRecord ?? this.recordCount);\n    if (start >= end) return;\n\n    const { recordBytes } = this.header;\n    /*\n      Checked rather than handed to Buffer.alloc.\n\n      `chunkBytes: NaN` came back as `RangeError: The value of \"size\" is out of range` from\n      inside Node, with no mention of the option that caused it — while a fractional\n      `startRecord` two lines up gets a typed EdfError naming the field. Every other option\n      here is checked; this one reached the allocator.\n    */\n    const budget = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;\n    if (!Number.isFinite(budget) || budget < 1) {\n      throw new EdfError(\n        'UNREADABLE',\n        `chunkBytes must be a positive number of bytes, got ${String(options.chunkBytes)}.`,\n        'It is a ceiling on how much of the file is held at once; one record is read whatever it says.',\n      );\n    }\n    /*\n      The budget is a ceiling, not an amount to reserve.\n\n      `Math.floor(budget / recordBytes)` is how many records would fit in it, and the buffer\n      was that many — whether or not the file had that many. A 848-byte fixture read with a\n      512 MB budget allocated 536,870,880 bytes for its two records, and every ordinary read\n      of a small file reserved the full 8 MB default. Nothing was wrong with the data; the\n      memory just had nothing to do with it.\n\n      Bounded by what is actually going to be read, so a batch of five hundred short\n      recordings costs five hundred short buffers rather than five hundred 8 MB ones.\n    */\n    const perChunk = Math.max(1, Math.min(Math.floor(budget / recordBytes), end - start));\n    const buffer = Buffer.alloc(perChunk * recordBytes);\n\n    for (let record = start; record < end; record += perChunk) {\n      const count = Math.min(perChunk, end - record);\n      const bytes = count * recordBytes;\n      const position = this.header.headerBytes + record * recordBytes;\n\n      const bytesRead = await readFully(this.#handle, buffer, 0, bytes, position);\n      if (bytesRead < bytes) {\n        // The file is shorter than its own size said. Quietly stopping here would\n        // hand back a conversion missing its tail with nothing to show for it.\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${bytes} bytes of data at record ${record} but only ${bytesRead} were ` +\n            `available; the file appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n\n      yield { firstRecordIndex: record, recordCount: count, data: buffer.subarray(0, bytes) };\n    }\n  }\n\n  /** Read one sample as its raw digital value. */\n  sampleAt(batch: RecordBatch, recordOffset: number, signal: EdfSignal, sampleIndex: number): number {\n    const position =\n      recordOffset * this.header.recordBytes +\n      signal.byteOffsetInRecord +\n      sampleIndex * this.header.bytesPerSample;\n\n    if (this.header.bytesPerSample === 3) {\n      // BDF stores 24-bit little-endian two's complement. Loading the three bytes\n      // into the top of a 32-bit word and shifting back down sign-extends them.\n      const data = batch.data;\n      return (\n        ((data[position] as number) << 8) |\n        ((data[position + 1] as number) << 16) |\n        ((data[position + 2] as number) << 24)\n      ) >> 8;\n    }\n    return readInt16LE(batch.data, position);\n  }\n\n  /** Byte offset of a signal's samples within a batch. */\n  offsetOf(batch: RecordBatch, recordOffset: number, signal: EdfSignal): number {\n    return recordOffset * this.header.recordBytes + signal.byteOffsetInRecord;\n  }\n\n  /** The annotation channel's raw bytes for one record in a batch. */\n  annotationBytes(batch: RecordBatch, recordOffset: number, signal: EdfSignal): Uint8Array {\n    const start = this.offsetOf(batch, recordOffset, signal);\n    return batch.data.subarray(start, start + signal.samplesPerRecord * this.header.bytesPerSample);\n  }\n\n  /**\n   * Read every EDF+ annotation in the file, plus the start time each record declares.\n   *\n   * Only the annotation channel is read, seeking straight to it inside each record\n   * rather than pulling whole records through memory. On a multi-gigabyte recording\n   * that is the difference between a few kilobytes of I/O and all of it.\n   *\n   * The whole file is always scanned, never just the records inside a requested\n   * window: writers are not obliged to store an annotation in the record its onset\n   * falls in, and some put every annotation in the first record. Reading only the\n   * window's records would drop those entirely.\n   */\n  /**\n   * Where this continuous recording begins, from the first record that says.\n   *\n   * A few records' worth of annotation bytes rather than the whole channel. A continuous\n   * recording's origin is the fraction of a second by which its first record follows the\n   * header's start time, and `--info` needs that to place a requested window — but it does\n   * not need the events, and finding one number by reading every record costs a seek per\n   * record across the whole file, which is the scan `--info` was deliberately spared.\n   *\n   * It reads on past record 0 because a conversion does. This used to stop there, so the\n   * moment one timekeeping TAL was unreadable the two disagreed: the conversion took the\n   * origin from record 1 and timed the file from 0.5s, while `--info` found nothing at\n   * record 0 and reported a recording starting at zero — the same file described two ways by\n   * one tool. Records are contiguous, so record `i` beginning at `t` puts the origin at\n   * `t - i * duration`, and any one of them settles it.\n   *\n   * The bound is what keeps this cheap: a file whose first `RECORDS_SEARCHED_FOR_ORIGIN`\n   * timekeeping entries are all unreadable reports an origin of zero here, and converting it\n   * raises ANNOTATION_DECODE_FAILED for every one of them.\n   *\n   * Returns null when there is nothing to read it from, in which case the origin is zero.\n   */\n  async readOrigin(): Promise<number | null> {\n    return (await this.scanOrigin()).origin;\n  }\n\n  /**\n   * The origin, and what the search saw on the way to it.\n   *\n   * `--info` takes this route for a continuous recording rather than reading every record,\n   * and reported nothing when the timekeeping it read was unreadable: the count was hard-coded\n   * to zero at the call site, so a file whose first TAL cannot be parsed raised\n   * ANNOTATION_DECODE_FAILED when converted and nothing under `--info`. Its byte-identical\n   * EDF+D twin — same bytes but for the reserved field, which has nothing to do with the\n   * defect — raised it both ways, because that path reads every record and counts as it goes.\n   *\n   * The failure was being read and then thrown away. `readOrigin` keeps its shape for callers\n   * who only want the number.\n   */\n  async scanOrigin(): Promise<{ origin: number | null; malformedTimekeeping: number }> {\n    this.#assertOpen();\n\n    let malformedTimekeeping = 0;\n    const channel = this.timekeepingSignal;\n    if (!channel || this.recordCount === 0) return { origin: null, malformedTimekeeping };\n\n    const { headerBytes, bytesPerSample, recordBytes, recordDuration } = this.header;\n    const buffer = Buffer.alloc(channel.samplesPerRecord * bytesPerSample);\n    if (buffer.length === 0) return { origin: null, malformedTimekeeping };\n\n    const searched = Math.min(this.recordCount, RECORDS_SEARCHED_FOR_ORIGIN);\n    for (let record = 0; record < searched; record++) {\n      const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n      const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n      if (bytesRead < buffer.length) return { origin: null, malformedTimekeeping };\n\n      const decoded = decodeRecordAnnotations(buffer, record);\n      malformedTimekeeping += decoded.malformedTimekeeping;\n      if (decoded.recordStart !== null) {\n        return { origin: decoded.recordStart - record * recordDuration, malformedTimekeeping };\n      }\n    }\n    return { origin: null, malformedTimekeeping };\n  }\n\n  async readAnnotations(): Promise<{\n    annotations: Annotation[];\n    recordStarts: (number | null)[];\n    malformed: number;\n    /** Unreadable TALs in first position, which carry timing rather than an event. */\n    malformedTimekeeping: number;\n    /** Events kept whose stated duration could not be read; see Annotation.duration. */\n    unreadableDurations: number;\n  }> {\n    this.#assertOpen();\n\n    const annotations: Annotation[] = [];\n    const recordStarts: (number | null)[] = new Array<number | null>(this.recordCount).fill(null);\n    let malformed = 0;\n    let malformedTimekeeping = 0;\n    let unreadableDurations = 0;\n\n    const channels = this.annotationSignals;\n    if (channels.length === 0) {\n      return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };\n    }\n\n    const { headerBytes, recordBytes, bytesPerSample } = this.header;\n    const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));\n    const timekeeping = this.timekeepingSignal;\n\n    for (let record = 0; record < this.recordCount; record++) {\n      for (const [position, channel] of channels.entries()) {\n        const buffer = buffers[position];\n        if (!buffer || buffer.length === 0) continue;\n\n        const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n        const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n        if (bytesRead < buffer.length) {\n          throw changedWhileReading(record, buffer.length, bytesRead, 'annotation data');\n        }\n\n        // Only the timekeeping channel carries the record's start; see timekeepingSignal.\n        const decoded = decodeRecordAnnotations(buffer, record, channel === timekeeping);\n        if (channel === timekeeping) recordStarts[record] = decoded.recordStart;\n        for (const annotation of decoded.annotations) annotations.push(annotation);\n        malformed += decoded.malformed;\n        malformedTimekeeping += decoded.malformedTimekeeping;\n        unreadableDurations += decoded.unreadableDurations;\n      }\n    }\n\n    annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);\n    return { annotations, recordStarts, malformed, malformedTimekeeping, unreadableDurations };\n  }\n\n  async close(): Promise<void> {\n    if (this.#closed) return;\n    this.#closed = true;\n    await this.#handle.close();\n  }\n\n  #assertOpen(): void {\n    if (this.#closed) throw new EdfError('UNREADABLE', 'This EDF file has already been closed.');\n  }\n}\n\nfunction describe(cause: unknown): string {\n  if (cause instanceof Error) {\n    const code = (cause as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return 'no such file';\n    if (code === 'EACCES') return 'permission denied';\n    return cause.message;\n  }\n  return String(cause);\n}\n\n/**\n * The most `fs.read` will accept as a length.\n *\n * Node asserts on a length that does not fit in a signed 32-bit integer, and it asserts in\n * C++: `Assertion failed: args[3]->IsInt32()`, forty frames of native stack, SIGABRT. Not an\n * exception — nothing in JavaScript sees it, so no catch block and no `uncaughtException`\n * handler runs, and a library consumer's whole process goes down with it.\n *\n * A round gigabyte rather than the exact limit, so the loop below does whole even reads.\n */\nconst MAX_READ_BYTES = 1024 * 1024 * 1024;\n\n/** Fill a requested region unless EOF is reached; regular-file reads may legally be short. */\nasync function readFully(\n  handle: FileHandle,\n  buffer: Buffer,\n  offset: number,\n  length: number,\n  position: number,\n): Promise<number> {\n  let total = 0;\n  while (total < length) {\n    /*\n      Capped, because one data record can be larger than a single read may be.\n\n      A record is read in one call when it exceeds the chunk budget — there is nothing\n      smaller to divide it by, since a record is the unit the format is addressed in. EDF's\n      samples-per-record field is 8 characters, so eleven channels at 99,999,999 samples make\n      a record of 2.2 GB, and a long record duration at ordinary rates gets there too. That\n      went to `fs.read` as a single length over 2^31-1 and took the process out with a native\n      assertion rather than an error.\n\n      Looping was already how a short read is handled, so the cap costs one more iteration\n      per gigabyte and nothing else.\n    */\n    const want = Math.min(length - total, MAX_READ_BYTES);\n    const { bytesRead } = await handle.read(buffer, offset + total, want, position + total);\n    if (bytesRead === 0) break;\n    total += bytesRead;\n  }\n  return total;\n}\n\nfunction changedWhileReading(\n  record: number,\n  expected: number,\n  actual: number,\n  subject = 'data',\n): EdfError {\n  return new EdfError(\n    'UNREADABLE',\n    `Expected ${expected} bytes of ${subject} at record ${record} but only ${actual} were ` +\n      `available; the file appears to have changed size while it was being read.`,\n    'Make sure the recording is not still being written to, then try again.',\n  );\n}\n"]}
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/edf/reader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Chunked reader for EDF / EDF+ files.\n *\n * Data records are read in batches sized by a byte budget rather than all at once,\n * so peak memory stays flat regardless of how long the recording is. A 4 GB file\n * and a 4 MB file use the same working set.\n */\n\nimport { open, stat } from 'node:fs/promises';\nimport type { FileHandle } from 'node:fs/promises';\n\nimport { createHash } from 'node:crypto';\n\nimport { EdfError } from './errors.js';\nimport type { Diagnostic } from './errors.js';\nimport { FIXED_HEADER_BYTES, SIGNAL_HEADER_BYTES, parseHeader, peekSignalCount } from './header.js';\nimport type { EdfHeader, EdfSignal } from './header.js';\nimport { decodeRecordAnnotations } from './annotations.js';\nimport type { Annotation } from './annotations.js';\nimport { decodeLatin1, readInt16LE } from './bytes.js';\n\n/**\n * How far `readOrigin` looks for a record that states its own start time.\n *\n * Enough that one or two unreadable timekeeping entries at the top of a file cost nothing,\n * few enough that `--info` stays a header read rather than a scan.\n */\nconst RECORDS_SEARCHED_FOR_ORIGIN = 16;\n\n/** Default read budget per batch. Large enough to amortise syscalls, small enough to stay cheap. */\nexport const DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;\n\nexport interface RecordBatch {\n  /** Index of the first record in this batch, relative to the whole file. */\n  firstRecordIndex: number;\n  recordCount: number;\n  /**\n   * Raw record bytes, `recordCount * header.recordBytes` long.\n   *\n   * The buffer is reused between iterations. Copy anything you need to keep past\n   * the current loop turn.\n   */\n  data: Uint8Array;\n}\n\nexport interface ReadRecordsOptions {\n  /** First record to read, inclusive. Defaults to 0. */\n  startRecord?: number;\n  /** Last record to read, exclusive. Defaults to the file's record count. */\n  endRecord?: number;\n  chunkBytes?: number;\n}\n\nexport class EdfFile {\n  readonly path: string;\n  readonly fileSize: number;\n  /**\n   * Last-modified time when this file was opened, in milliseconds, for the same reason as\n   * `fileSize`.\n   *\n   * Kept as the raw number rather than a Date because `new Date(ms).getTime()` truncates to\n   * whole milliseconds: comparing that against a later `fstat`, which carries the\n   * filesystem's sub-millisecond precision, reported every undisturbed conversion as one\n   * whose input had changed underneath it.\n   */\n  readonly modifiedAtOpenMs: number;\n  readonly header: EdfHeader;\n  /** Records actually present in the file, which may differ from the header's claim. */\n  readonly recordCount: number;\n  readonly trailingBytes: number;\n  readonly diagnostics: Diagnostic[];\n\n  #handle: FileHandle;\n  #closed = false;\n  /** The last answer `changedSinceOpen` computed, so it survives the file being closed. */\n  #changed: boolean | null = null;\n\n  private constructor(init: {\n    path: string;\n    fileSize: number;\n    modifiedAtOpenMs: number;\n    header: EdfHeader;\n    recordCount: number;\n    trailingBytes: number;\n    diagnostics: Diagnostic[];\n    handle: FileHandle;\n  }) {\n    this.path = init.path;\n    this.fileSize = init.fileSize;\n    this.modifiedAtOpenMs = init.modifiedAtOpenMs;\n    this.header = init.header;\n    this.recordCount = init.recordCount;\n    this.trailingBytes = init.trailingBytes;\n    this.diagnostics = init.diagnostics;\n    this.#handle = init.handle;\n  }\n\n  /**\n   * SHA-256 of the bytes this conversion actually read.\n   *\n   * Hashed through the open descriptor, over exactly the `fileSize` bytes that were there\n   * when the file was opened — the same number every record count and window in the output\n   * was derived from. Re-opening the path to hash it afterwards described whatever was at\n   * that name by then: a recording still being written grew from 2,000 records to 3,000\n   * mid-conversion and metadata.json recorded `data_records: 2000` beside the checksum and\n   * byte count of the 3,000-record file, which is provenance for bytes nobody converted.\n   * Replacing the file at that path did the same thing more completely.\n   */\n  async sha256(): Promise<string> {\n    this.#assertOpen();\n    const hash = createHash('sha256');\n    const buffer = Buffer.alloc(Math.min(this.fileSize, 4 * 1024 * 1024) || 1);\n    for (let at = 0; at < this.fileSize; ) {\n      const want = Math.min(buffer.length, this.fileSize - at);\n      const { bytesRead } = await this.#handle.read(buffer, 0, want, at);\n      if (bytesRead <= 0) {\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${this.fileSize} bytes to checksum but the file ended at ${at}; ` +\n            `it appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n      hash.update(buffer.subarray(0, bytesRead));\n      at += bytesRead;\n    }\n    return hash.digest('hex');\n  }\n\n  /**\n   * Whether the file has changed since it was opened, by size or by modification time.\n   *\n   * Checked through the descriptor, so it answers for the bytes that were read rather than\n   * for whatever now answers to the same name. A recording still being written is the\n   * ordinary cause, and the conversion is still correct for the data it saw — it is the\n   * claim that the output describes the file as it now stands that stops being true.\n   */\n  async changedSinceOpen(): Promise<boolean> {\n    /*\n      A closed file remembers its last answer rather than inventing a new one.\n\n      Returning false once closed asserted \"it did not change\", which is not something a\n      closed descriptor can know — and `convert()` closes the file before it returns, so\n      `result.file.changedSinceOpen()` denied the very change the INPUT_CHANGED diagnostic\n      in the same result object had just reported. One object, two answers.\n\n      `convert()` always asks before closing, so the cached answer is the true one. A caller\n      who closed the file without ever asking gets an error, which is the same treatment\n      every other method on a closed file gets.\n    */\n    if (this.#closed) {\n      if (this.#changed !== null) return this.#changed;\n      throw new EdfError(\n        'UNREADABLE',\n        `\"${this.path}\" is closed, and whether it changed while it was open was never checked.`,\n        'Ask before closing the file. A ConvertResult carries the answer already, since ' +\n          'convert() checks it on the way out.',\n      );\n    }\n    const now = await this.#handle.stat().catch(() => null);\n    if (now === null) return this.#changed ?? false;\n    this.#changed = now.size !== this.fileSize || now.mtimeMs !== this.modifiedAtOpenMs;\n    return this.#changed;\n  }\n\n  static async open(path: string): Promise<EdfFile> {\n    const info = await stat(path).catch((cause: unknown) => {\n      throw new EdfError('UNREADABLE', `Cannot read \"${path}\": ${describe(cause)}`);\n    });\n    if (info.isDirectory()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is a directory, not an EDF file.`);\n    }\n    if (!info.isFile()) {\n      throw new EdfError('UNREADABLE', `\"${path}\" is not a regular file.`);\n    }\n\n    const handle = await open(path, 'r');\n    try {\n      const fixed = Buffer.alloc(Math.min(FIXED_HEADER_BYTES, info.size));\n      if (fixed.length > 0) {\n        const bytesRead = await readFully(handle, fixed, 0, fixed.length, 0);\n        if (bytesRead < fixed.length) throw changedWhileReading(0, fixed.length, bytesRead);\n      }\n\n      // The signal count decides how much more header there is to read. Read by the header\n      // parser itself, so the two cannot disagree about which files are readable: this used\n      // to have its own Number(), which tolerated the NUL padding sloppy writers emit but\n      // not the comma decimal separator that COMMA_DECIMAL exists to accept.\n      let headerBuffer = fixed;\n      if (fixed.length === FIXED_HEADER_BYTES) {\n        const ns = peekSignalCount(fixed);\n        if (ns !== null) {\n          const total = FIXED_HEADER_BYTES + ns * SIGNAL_HEADER_BYTES;\n          if (total <= info.size) {\n            headerBuffer = Buffer.alloc(total);\n            const bytesRead = await readFully(handle, headerBuffer, 0, total, 0);\n            if (bytesRead < total) throw changedWhileReading(0, total, bytesRead);\n          }\n        }\n      }\n\n      const { header, recordCount, trailingBytes, diagnostics } = parseHeader(\n        headerBuffer,\n        info.size,\n      );\n\n      return new EdfFile({\n        path,\n        fileSize: info.size,\n        modifiedAtOpenMs: info.mtimeMs,\n        header,\n        recordCount,\n        trailingBytes,\n        diagnostics,\n        handle,\n      });\n    } catch (error) {\n      await handle.close().catch(() => {});\n      throw error;\n    }\n  }\n\n  /** Signal channels, excluding the EDF+ annotations channel. */\n  get dataSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => !s.isAnnotations);\n  }\n\n  /**\n   * The annotation channel a record's start time is read from.\n   *\n   * EDF+ puts the timekeeping TAL first in the first annotation channel, and this was read as\n   * `annotationSignals[0]` — the first one declared, whether or not it can hold anything. A\n   * writer that declares an annotation channel and gives it zero samples per record leaves a\n   * slot of zero bytes, so nothing was read from it, and the timekeeping in the channel after\n   * it went unread: a three-record EDF+D reported \"3 of 3 data records carry no readable\n   * timekeeping annotation\" about three that were perfectly readable, and timed the file from\n   * zero.\n   *\n   * A channel with no room carries nothing, so it is not the one the TAL is in.\n   */\n  get timekeepingSignal(): EdfSignal | undefined {\n    return this.annotationSignals.find((signal) => signal.samplesPerRecord > 0);\n  }\n\n  get annotationSignals(): EdfSignal[] {\n    return this.header.signals.filter((s) => s.isAnnotations);\n  }\n\n  /** Total recording duration in seconds, based on records actually present. */\n  get durationSeconds(): number {\n    return this.recordCount * this.header.recordDuration;\n  }\n\n  /** Read a half-open range of records in batches. */\n  async *readRecords(options: ReadRecordsOptions = {}): AsyncGenerator<RecordBatch> {\n    this.#assertOpen();\n\n    /*\n      Record bounds have to be whole records.\n\n      A fractional `startRecord` was carried straight into `position = headerBytes +\n      record * recordBytes`, so reading from 1.5 began half a record in and every sample\n      after it was decoded from the wrong offset: on the two-channel test fixture it\n      returned channel 2's values under channel 1's signal, with no error. Clamping\n      silently would be no better, since a caller asking for record 1.5 has a bug the\n      library should name rather than paper over.\n    */\n    for (const [name, value] of [\n      ['startRecord', options.startRecord],\n      ['endRecord', options.endRecord],\n    ] as const) {\n      if (value !== undefined && !Number.isInteger(value)) {\n        throw new EdfError(\n          'BAD_HEADER_FIELD',\n          `readRecords: ${name} must be a whole record index, got ${value}.`,\n          'Record boundaries are the unit the file can be read in; a fractional index would decode samples from the middle of a record.',\n        );\n      }\n    }\n\n    const start = Math.max(0, options.startRecord ?? 0);\n    const end = Math.min(this.recordCount, options.endRecord ?? this.recordCount);\n    if (start >= end) return;\n\n    const { recordBytes } = this.header;\n    /*\n      Checked rather than handed to Buffer.alloc.\n\n      `chunkBytes: NaN` came back as `RangeError: The value of \"size\" is out of range` from\n      inside Node, with no mention of the option that caused it — while a fractional\n      `startRecord` two lines up gets a typed EdfError naming the field. Every other option\n      here is checked; this one reached the allocator.\n    */\n    const budget = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;\n    if (!Number.isFinite(budget) || budget < 1) {\n      throw new EdfError(\n        'UNREADABLE',\n        `chunkBytes must be a positive number of bytes, got ${String(options.chunkBytes)}.`,\n        'It is a ceiling on how much of the file is held at once; one record is read whatever it says.',\n      );\n    }\n    /*\n      The budget is a ceiling, not an amount to reserve.\n\n      `Math.floor(budget / recordBytes)` is how many records would fit in it, and the buffer\n      was that many — whether or not the file had that many. A 848-byte fixture read with a\n      512 MB budget allocated 536,870,880 bytes for its two records, and every ordinary read\n      of a small file reserved the full 8 MB default. Nothing was wrong with the data; the\n      memory just had nothing to do with it.\n\n      Bounded by what is actually going to be read, so a batch of five hundred short\n      recordings costs five hundred short buffers rather than five hundred 8 MB ones.\n    */\n    const perChunk = Math.max(1, Math.min(Math.floor(budget / recordBytes), end - start));\n    const buffer = Buffer.alloc(perChunk * recordBytes);\n\n    for (let record = start; record < end; record += perChunk) {\n      const count = Math.min(perChunk, end - record);\n      const bytes = count * recordBytes;\n      const position = this.header.headerBytes + record * recordBytes;\n\n      const bytesRead = await readFully(this.#handle, buffer, 0, bytes, position);\n      if (bytesRead < bytes) {\n        // The file is shorter than its own size said. Quietly stopping here would\n        // hand back a conversion missing its tail with nothing to show for it.\n        throw new EdfError(\n          'UNREADABLE',\n          `Expected ${bytes} bytes of data at record ${record} but only ${bytesRead} were ` +\n            `available; the file appears to have changed size while it was being read.`,\n          'Make sure the recording is not still being written to, then try again.',\n        );\n      }\n\n      yield { firstRecordIndex: record, recordCount: count, data: buffer.subarray(0, bytes) };\n    }\n  }\n\n  /** Read one sample as its raw digital value. */\n  sampleAt(batch: RecordBatch, recordOffset: number, signal: EdfSignal, sampleIndex: number): number {\n    const position =\n      recordOffset * this.header.recordBytes +\n      signal.byteOffsetInRecord +\n      sampleIndex * this.header.bytesPerSample;\n\n    if (this.header.bytesPerSample === 3) {\n      // BDF stores 24-bit little-endian two's complement. Loading the three bytes\n      // into the top of a 32-bit word and shifting back down sign-extends them.\n      const data = batch.data;\n      return (\n        ((data[position] as number) << 8) |\n        ((data[position + 1] as number) << 16) |\n        ((data[position + 2] as number) << 24)\n      ) >> 8;\n    }\n    return readInt16LE(batch.data, position);\n  }\n\n  /** Byte offset of a signal's samples within a batch. */\n  offsetOf(batch: RecordBatch, recordOffset: number, signal: EdfSignal): number {\n    return recordOffset * this.header.recordBytes + signal.byteOffsetInRecord;\n  }\n\n  /** The annotation channel's raw bytes for one record in a batch. */\n  annotationBytes(batch: RecordBatch, recordOffset: number, signal: EdfSignal): Uint8Array {\n    const start = this.offsetOf(batch, recordOffset, signal);\n    return batch.data.subarray(start, start + signal.samplesPerRecord * this.header.bytesPerSample);\n  }\n\n  /**\n   * Read every EDF+ annotation in the file, plus the start time each record declares.\n   *\n   * Only the annotation channel is read, seeking straight to it inside each record\n   * rather than pulling whole records through memory. On a multi-gigabyte recording\n   * that is the difference between a few kilobytes of I/O and all of it.\n   *\n   * The whole file is always scanned, never just the records inside a requested\n   * window: writers are not obliged to store an annotation in the record its onset\n   * falls in, and some put every annotation in the first record. Reading only the\n   * window's records would drop those entirely.\n   */\n  /**\n   * Where this continuous recording begins, from the first record that says.\n   *\n   * A few records' worth of annotation bytes rather than the whole channel. A continuous\n   * recording's origin is the fraction of a second by which its first record follows the\n   * header's start time, and `--info` needs that to place a requested window — but it does\n   * not need the events, and finding one number by reading every record costs a seek per\n   * record across the whole file, which is the scan `--info` was deliberately spared.\n   *\n   * It reads on past record 0 because a conversion does. This used to stop there, so the\n   * moment one timekeeping TAL was unreadable the two disagreed: the conversion took the\n   * origin from record 1 and timed the file from 0.5s, while `--info` found nothing at\n   * record 0 and reported a recording starting at zero — the same file described two ways by\n   * one tool. Records are contiguous, so record `i` beginning at `t` puts the origin at\n   * `t - i * duration`, and any one of them settles it.\n   *\n   * The bound is what keeps this cheap: a file whose first `RECORDS_SEARCHED_FOR_ORIGIN`\n   * timekeeping entries are all unreadable reports an origin of zero here, and converting it\n   * raises ANNOTATION_DECODE_FAILED for every one of them.\n   *\n   * Returns null when there is nothing to read it from, in which case the origin is zero.\n   */\n  async readOrigin(): Promise<number | null> {\n    return (await this.scanOrigin()).origin;\n  }\n\n  /**\n   * The origin, and what the search saw on the way to it.\n   *\n   * `--info` takes this route for a continuous recording rather than reading every record,\n   * and reported nothing when the timekeeping it read was unreadable: the count was hard-coded\n   * to zero at the call site, so a file whose first TAL cannot be parsed raised\n   * ANNOTATION_DECODE_FAILED when converted and nothing under `--info`. Its byte-identical\n   * EDF+D twin — same bytes but for the reserved field, which has nothing to do with the\n   * defect — raised it both ways, because that path reads every record and counts as it goes.\n   *\n   * The failure was being read and then thrown away. `readOrigin` keeps its shape for callers\n   * who only want the number.\n   */\n  async scanOrigin(): Promise<{ origin: number | null; malformedTimekeeping: number }> {\n    this.#assertOpen();\n\n    let malformedTimekeeping = 0;\n    const channel = this.timekeepingSignal;\n    if (!channel || this.recordCount === 0) return { origin: null, malformedTimekeeping };\n\n    const { headerBytes, bytesPerSample, recordBytes, recordDuration } = this.header;\n    const buffer = Buffer.alloc(channel.samplesPerRecord * bytesPerSample);\n    if (buffer.length === 0) return { origin: null, malformedTimekeeping };\n\n    const searched = Math.min(this.recordCount, RECORDS_SEARCHED_FOR_ORIGIN);\n    for (let record = 0; record < searched; record++) {\n      const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n      const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n      if (bytesRead < buffer.length) return { origin: null, malformedTimekeeping };\n\n      const decoded = decodeRecordAnnotations(buffer, record);\n      malformedTimekeeping += decoded.malformedTimekeeping;\n      if (decoded.recordStart !== null) {\n        return { origin: decoded.recordStart - record * recordDuration, malformedTimekeeping };\n      }\n    }\n    return { origin: null, malformedTimekeeping };\n  }\n\n  async readAnnotations(): Promise<{\n    annotations: Annotation[];\n    recordStarts: (number | null)[];\n    malformed: number;\n    /** Unreadable TALs in first position, which carry timing rather than an event. */\n    malformedTimekeeping: number;\n    /** Events kept whose stated duration could not be read; see Annotation.duration. */\n    unreadableDurations: number;\n    /** Events kept whose stated duration read as a number below zero. */\n    negativeDurations: number;\n  }> {\n    this.#assertOpen();\n\n    const annotations: Annotation[] = [];\n    const recordStarts: (number | null)[] = new Array<number | null>(this.recordCount).fill(null);\n    let malformed = 0;\n    let malformedTimekeeping = 0;\n    let unreadableDurations = 0;\n    let negativeDurations = 0;\n\n    const channels = this.annotationSignals;\n    if (channels.length === 0) {\n      return {\n        annotations,\n        recordStarts,\n        malformed,\n        malformedTimekeeping,\n        unreadableDurations,\n        negativeDurations,\n      };\n    }\n\n    const { headerBytes, recordBytes, bytesPerSample } = this.header;\n    const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));\n    const timekeeping = this.timekeepingSignal;\n\n    for (let record = 0; record < this.recordCount; record++) {\n      for (const [position, channel] of channels.entries()) {\n        const buffer = buffers[position];\n        if (!buffer || buffer.length === 0) continue;\n\n        const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;\n        const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);\n        if (bytesRead < buffer.length) {\n          throw changedWhileReading(record, buffer.length, bytesRead, 'annotation data');\n        }\n\n        // Only the timekeeping channel carries the record's start; see timekeepingSignal.\n        const decoded = decodeRecordAnnotations(buffer, record, channel === timekeeping);\n        if (channel === timekeeping) recordStarts[record] = decoded.recordStart;\n        for (const annotation of decoded.annotations) annotations.push(annotation);\n        malformed += decoded.malformed;\n        malformedTimekeeping += decoded.malformedTimekeeping;\n        unreadableDurations += decoded.unreadableDurations;\n        negativeDurations += decoded.negativeDurations;\n      }\n    }\n\n    annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);\n    return {\n      annotations,\n      recordStarts,\n      malformed,\n      malformedTimekeeping,\n      unreadableDurations,\n      negativeDurations,\n    };\n  }\n\n  async close(): Promise<void> {\n    if (this.#closed) return;\n    this.#closed = true;\n    await this.#handle.close();\n  }\n\n  #assertOpen(): void {\n    if (this.#closed) throw new EdfError('UNREADABLE', 'This EDF file has already been closed.');\n  }\n}\n\nfunction describe(cause: unknown): string {\n  if (cause instanceof Error) {\n    const code = (cause as NodeJS.ErrnoException).code;\n    if (code === 'ENOENT') return 'no such file';\n    if (code === 'EACCES') return 'permission denied';\n    return cause.message;\n  }\n  return String(cause);\n}\n\n/**\n * The most `fs.read` will accept as a length.\n *\n * Node asserts on a length that does not fit in a signed 32-bit integer, and it asserts in\n * C++: `Assertion failed: args[3]->IsInt32()`, forty frames of native stack, SIGABRT. Not an\n * exception — nothing in JavaScript sees it, so no catch block and no `uncaughtException`\n * handler runs, and a library consumer's whole process goes down with it.\n *\n * A round gigabyte rather than the exact limit, so the loop below does whole even reads.\n */\nconst MAX_READ_BYTES = 1024 * 1024 * 1024;\n\n/** Fill a requested region unless EOF is reached; regular-file reads may legally be short. */\nasync function readFully(\n  handle: FileHandle,\n  buffer: Buffer,\n  offset: number,\n  length: number,\n  position: number,\n): Promise<number> {\n  let total = 0;\n  while (total < length) {\n    /*\n      Capped, because one data record can be larger than a single read may be.\n\n      A record is read in one call when it exceeds the chunk budget — there is nothing\n      smaller to divide it by, since a record is the unit the format is addressed in. EDF's\n      samples-per-record field is 8 characters, so eleven channels at 99,999,999 samples make\n      a record of 2.2 GB, and a long record duration at ordinary rates gets there too. That\n      went to `fs.read` as a single length over 2^31-1 and took the process out with a native\n      assertion rather than an error.\n\n      Looping was already how a short read is handled, so the cap costs one more iteration\n      per gigabyte and nothing else.\n    */\n    const want = Math.min(length - total, MAX_READ_BYTES);\n    const { bytesRead } = await handle.read(buffer, offset + total, want, position + total);\n    if (bytesRead === 0) break;\n    total += bytesRead;\n  }\n  return total;\n}\n\nfunction changedWhileReading(\n  record: number,\n  expected: number,\n  actual: number,\n  subject = 'data',\n): EdfError {\n  return new EdfError(\n    'UNREADABLE',\n    `Expected ${expected} bytes of ${subject} at record ${record} but only ${actual} were ` +\n      `available; the file appears to have changed size while it was being read.`,\n    'Make sure the recording is not still being written to, then try again.',\n  );\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edf2csv",
-  "version": "0.5.57",
+  "version": "0.5.59",
   "description": "Convert EDF, EDF+ and BDF biosignal recordings (European Data Format) to CSV from the command line. Local, streaming, and never resamples or alters units.",
   "keywords": [
     "edf",