edf2csv 0.5.114 → 0.5.116

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 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.116
+
+### Fixed: a recording it is not allowed to read came back as a raw Node error
+
+```
+error: EACCES: permission denied, open '/data/noread.edf'
+```
+
+Every neighbouring failure prints the tool's own sentence — `Cannot read "nope.edf": no such
+file` — and the library raises an `EdfError` whose `code` says which kind of failure it was.
+This one printed Node's errno text with no hint, and threw a plain `Error` whose `code` was
+`EACCES`.
+
+`stat` needs the parent directory searchable and says nothing about the file's own mode, so a
+recording with no read permission passes it and fails at the open two lines later, which was
+the one call not wrapped. Denying the *directory* was translated correctly, which is why this
+looked covered.
+
+api.md says `UNREADABLE` "covers a missing file, a directory passed where a file was expected,
+a permission failure, and a file that changed size while being read. Branch on `code`, never on
+the message text." A consumer doing exactly that fell through to its generic handler for the
+commonest permission failure there is.
+
+```
+error: Cannot read "/data/noread.edf": permission denied
+```
+
+The test skips itself where the file turns out to be readable anyway, since root reads a mode-000
+file regardless and there would be nothing to assert.
+
+## 0.5.115
+
+### Fixed: the padding at the end of an annotation slot was exported as an event
+
+A file holding two events wrote four rows:
+
+```
+onset_s,duration_s,description,record_index
+0.5,,Lights off,0
+0.5,,          ,0
+1.5,,Lights off,1
+1.5,,          ,1
+```
+
+The invented rows carry the real event's onset, so anything keyed on `onset_s` saw each event
+twice, and `annotations_written` and the run summary agreed with the larger number. No warning.
+
+The decoder already refuses to call a run of spaces a lost annotation — but that check sees only
+the chunks between NULs, and a writer that leaves its last TAL unterminated puts the fill inside
+the chunk, after the final `0x14`. Split on that separator it is a text segment like any other,
+and `" "` is not `""`.
+
+A text segment that is nothing but slot fill — space, tab, CR, LF or NUL — is padding now, by the
+same rule the chunk-level check uses. An event whose description is genuinely nothing but spaces
+cannot be told from fill at this level; inventing rows out of fill is the worse of the two
+answers, and it is the one that was being given.
+
 ## 0.5.114
 
 ### Fixed: "No event was lost" printed over a conversion that lost four

package/dist/edf/annotations.js

@@ -199,8 +199,22 @@ function parseTal(chunk, recordIndex) {
     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.
-        if (raw === '')
+        /*
+          A trailing separator yields an empty segment; a timekeeping TAL is all empty.
+    
+          Whitespace counts as empty here, which it did not, and the padding at the end of the
+          slot became an event. The chunk loop above already refuses to call a run of spaces a
+          lost annotation — but it only sees chunks between NULs, and a writer that leaves its
+          last TAL unterminated puts the fill *inside* the chunk, after the final 0x14. Split on
+          that separator it is a text segment like any other, and " " is not "".
+    
+          A file holding two events exported four rows: `0.5,,Lights off,0` and `0.5,,   ,0`,
+          twice, sharing the real event's onset, with annotations_written and the run summary
+          agreeing with the inflated number and nothing warned. An event whose description is
+          genuinely nothing but spaces cannot be told from fill, and inventing rows out of fill
+          is the worse of the two answers.
+        */
+        if ([...raw].every((c) => isPaddingByte(c.charCodeAt(0))))
             continue;
         annotations.push({
             onset,

package/dist/edf/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,yDAAyD;AAChF,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,gCAAgC;AAC3D,MAAM,OAAO,GAAG,IAAI,CAAC;AAErB,MAAM,aAAa,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;AACpD,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;AAmE5D;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAiB,EACjB,WAAmB,EACnB,kBAAkB,GAAG,IAAI;IAEzB,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,UAAU,GAAG,IAAI,CAAC;IACtB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAC7B,IAAI,4BAA4B,GAAG,CAAC,CAAC;IACrC,IAAI,mBAAmB,GAAG,CAAC,CAAC;IAC5B,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAE1B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO;YAAE,SAAS;QAEzD,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACvC;;;;;;;;;;;;cAYE;YACF,IAAI,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC/B,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YAE5C,+EAA+E;YAC/E,mFAAmF;YACnF,+EAA+E;YAC/E,iFAAiF;YACjF,+EAA+E;YAC/E,uEAAuE;YACvE;;;;;;;;;cASE;YACF,MAAM,aAAa,GAAG,UAAU,IAAI,kBAAkB,CAAC;YACvD,UAAU,GAAG,KAAK,CAAC;YAEnB,IAAI,MAAM,EAAE,CAAC;gBACX,IAAI,aAAa;oBAAE,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;gBAC9C,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,WAAW;oBAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAC1E,mBAAmB,IAAI,MAAM,CAAC,mBAAmB,CAAC;gBAClD,iBAAiB,IAAI,MAAM,CAAC,iBAAiB,CAAC;YAChD,CAAC;iBAAM,CAAC;gBACN;;;;;;;;;;;;;;;;kBAgBE;gBACF,IAAI,aAAa,EAAE,CAAC;oBAClB,oBAAoB,EAAE,CAAC;oBACvB,IAAI,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAC;wBACjC,4BAA4B,EAAE,CAAC;wBAC/B,SAAS,EAAE,CAAC;oBACd,CAAC;gBACH,CAAC;;oBAAM,SAAS,EAAE,CAAC;YACrB,CAAC;QACH,CAAC;QACD,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;IAED,OAAO;QACL,WAAW;QACX,WAAW;QACX,SAAS;QACT,oBAAoB;QACpB,4BAA4B;QAC5B,mBAAmB;QACnB,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAWD;;;;;;GAMG;AACH,SAAS,qBAAqB,CAAC,KAAiB;IAC9C,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,cAAc,GAAG,IAAI,CAAC;YACtB,SAAS;QACX,CAAC;QACD,IAAI,cAAc,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IAC1D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC;AAC3F,CAAC;AAED,SAAS,QAAQ,CAAC,KAAiB,EAAE,WAAmB;IACtD,mEAAmE;IACnE,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,KAAK,KAAK,IAAI,CAAC,OAAO,IAAI,KAAK,KAAK,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAElE,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAE5B,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,YAAY,GAAkB,IAAI,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACpD,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;QACvC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC;;;;;;;;;;MAUE;IACF,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,kBAAkB,GAAG,KAAK,CAAC;IAC/B,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,QAAQ,GAAG,CAAC,CAAC;;YAChC,kBAAkB,GAAG,IAAI,CAAC;IACjC,CAAC;IAED;;;;;;;;;MASE;IACF,MAAM,gBAAgB,GAAG,QAAQ,KAAK,IAAI,IAAI,QAAQ,GAAG,CAAC,CAAC;IAE3D,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,gFAAgF;QAChF,IAAI,GAAG,KAAK,EAAE;YAAE,SAAS;QACzB,WAAW,CAAC,IAAI,CAAC;YACf,KAAK;YACL,QAAQ;YACR,IAAI,EAAE,GAAG;YACT,WAAW;YACX,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAC,CAAC;IACL,CAAC;IAED,yFAAyF;IACzF,+CAA+C;IAC/C,OAAO;QACL,KAAK;QACL,WAAW;QACX,mBAAmB,EAAE,kBAAkB,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChE,iBAAiB,EAAE,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC","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   * True when the file stated a duration that could not be read.\n   *\n   * `duration` is null either way, which is the ambiguity the counts beside it exist to\n   * flag — and those counts were of the whole file while `annotations.csv` is filtered to\n   * the requested window. A conversion of one second of a recording warned that \"1\n   * annotation states a duration that is not a number, so its duration_s cell is empty\"\n   * about an event two seconds outside it, and failed `--strict` for it. Carrying the fact\n   * on the event lets the count be taken where the window has already been applied.\n   */\n  durationUnreadable?: boolean;\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   * How many of those also carried event text, and so lost events as well as a position.\n   *\n   * A TAL in first position holds the record's start time, and may hold events after it — the\n   * specification allows both in the one entry, and writers use it. When such a TAL cannot be\n   * parsed, both are gone, and counting it only as lost timekeeping let the warning beside it\n   * say \"No event was lost\" over a conversion that had just dropped four of them.\n   *\n   * Counted rather than inferred, because the sentence has to be right in the ordinary case\n   * too: a bare timekeeping TAL really does lose no event, and that is nearly all of them.\n   */\n  malformedTimekeepingWithText: 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 malformedTimekeepingWithText = 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      /*\n        Padding is not a lost annotation.\n\n        The spec pads the slot with NUL, which the loop above already skips because it is what\n        separates one TAL from the next. Writers pad with spaces instead, and a run of spaces\n        after the last TAL is a non-empty chunk — so a file holding one perfectly readable\n        event, exported in full, was told \"2 annotation entries were unreadable and could not\n        be exported\", one per record. Nothing was lost. Under --strict that is a failed run\n        over the whitespace at the end of a slot.\n\n        Only whitespace. A chunk of anything else that does not parse is a real loss and is\n        still counted, which is the case this warning exists for.\n      */\n      if (chunk.every(isPaddingByte)) {\n        start = i + 1;\n        continue;\n      }\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          The other direction is just as wrong. A first-position TAL may carry events after\n          the start time, and when one of those cannot be parsed the events go with it — so\n          counting it only as lost timekeeping produced the opposite false sentence: \"No event\n          was lost\", printed over a run whose annotations.csv had gone from six rows to two.\n          It is one entry that could not be exported and one record with no position, and it\n          is counted as both.\n        */\n        if (isTimekeeping) {\n          malformedTimekeeping++;\n          if (carriesAnnotationText(chunk)) {\n            malformedTimekeepingWithText++;\n            malformed++;\n          }\n        } else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return {\n    recordStart,\n    annotations,\n    malformed,\n    malformedTimekeeping,\n    malformedTimekeepingWithText,\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\n/**\n * Whether a TAL that could not be parsed still carried event text.\n *\n * A TAL is `onset[<0x15>duration]<0x14>text<0x14>...`, so anything other than padding after\n * the first 0x14 is a description the file meant to export. Read from the raw chunk, since by\n * the time this is asked the parse has already failed and there is no structure to consult.\n */\nfunction carriesAnnotationText(chunk: Uint8Array): boolean {\n  let afterSeparator = false;\n  for (const byte of chunk) {\n    if (byte === 0x14) {\n      afterSeparator = true;\n      continue;\n    }\n    if (afterSeparator && !isPaddingByte(byte)) return true;\n  }\n  return false;\n}\n\n/** Space, tab, CR, LF or NUL — what a writer fills the rest of the slot with. */\nfunction isPaddingByte(byte: number): boolean {\n  return byte === 0x20 || byte === 0x09 || byte === 0x0d || byte === 0x0a || byte === 0x00;\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({\n      onset,\n      duration,\n      text: raw,\n      recordIndex,\n      ...(durationUnreadable ? { durationUnreadable: true } : {}),\n    });\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"]}
+{"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   * True when the file stated a duration that could not be read.\n   *\n   * `duration` is null either way, which is the ambiguity the counts beside it exist to\n   * flag — and those counts were of the whole file while `annotations.csv` is filtered to\n   * the requested window. A conversion of one second of a recording warned that \"1\n   * annotation states a duration that is not a number, so its duration_s cell is empty\"\n   * about an event two seconds outside it, and failed `--strict` for it. Carrying the fact\n   * on the event lets the count be taken where the window has already been applied.\n   */\n  durationUnreadable?: boolean;\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   * How many of those also carried event text, and so lost events as well as a position.\n   *\n   * A TAL in first position holds the record's start time, and may hold events after it — the\n   * specification allows both in the one entry, and writers use it. When such a TAL cannot be\n   * parsed, both are gone, and counting it only as lost timekeeping let the warning beside it\n   * say \"No event was lost\" over a conversion that had just dropped four of them.\n   *\n   * Counted rather than inferred, because the sentence has to be right in the ordinary case\n   * too: a bare timekeeping TAL really does lose no event, and that is nearly all of them.\n   */\n  malformedTimekeepingWithText: 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 malformedTimekeepingWithText = 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      /*\n        Padding is not a lost annotation.\n\n        The spec pads the slot with NUL, which the loop above already skips because it is what\n        separates one TAL from the next. Writers pad with spaces instead, and a run of spaces\n        after the last TAL is a non-empty chunk — so a file holding one perfectly readable\n        event, exported in full, was told \"2 annotation entries were unreadable and could not\n        be exported\", one per record. Nothing was lost. Under --strict that is a failed run\n        over the whitespace at the end of a slot.\n\n        Only whitespace. A chunk of anything else that does not parse is a real loss and is\n        still counted, which is the case this warning exists for.\n      */\n      if (chunk.every(isPaddingByte)) {\n        start = i + 1;\n        continue;\n      }\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          The other direction is just as wrong. A first-position TAL may carry events after\n          the start time, and when one of those cannot be parsed the events go with it — so\n          counting it only as lost timekeeping produced the opposite false sentence: \"No event\n          was lost\", printed over a run whose annotations.csv had gone from six rows to two.\n          It is one entry that could not be exported and one record with no position, and it\n          is counted as both.\n        */\n        if (isTimekeeping) {\n          malformedTimekeeping++;\n          if (carriesAnnotationText(chunk)) {\n            malformedTimekeepingWithText++;\n            malformed++;\n          }\n        } else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return {\n    recordStart,\n    annotations,\n    malformed,\n    malformedTimekeeping,\n    malformedTimekeepingWithText,\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\n/**\n * Whether a TAL that could not be parsed still carried event text.\n *\n * A TAL is `onset[<0x15>duration]<0x14>text<0x14>...`, so anything other than padding after\n * the first 0x14 is a description the file meant to export. Read from the raw chunk, since by\n * the time this is asked the parse has already failed and there is no structure to consult.\n */\nfunction carriesAnnotationText(chunk: Uint8Array): boolean {\n  let afterSeparator = false;\n  for (const byte of chunk) {\n    if (byte === 0x14) {\n      afterSeparator = true;\n      continue;\n    }\n    if (afterSeparator && !isPaddingByte(byte)) return true;\n  }\n  return false;\n}\n\n/** Space, tab, CR, LF or NUL — what a writer fills the rest of the slot with. */\nfunction isPaddingByte(byte: number): boolean {\n  return byte === 0x20 || byte === 0x09 || byte === 0x0d || byte === 0x0a || byte === 0x00;\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    /*\n      A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n\n      Whitespace counts as empty here, which it did not, and the padding at the end of the\n      slot became an event. The chunk loop above already refuses to call a run of spaces a\n      lost annotation — but it only sees chunks between NULs, and a writer that leaves its\n      last TAL unterminated puts the fill *inside* the chunk, after the final 0x14. Split on\n      that separator it is a text segment like any other, and \" \" is not \"\".\n\n      A file holding two events exported four rows: `0.5,,Lights off,0` and `0.5,,   ,0`,\n      twice, sharing the real event's onset, with annotations_written and the run summary\n      agreeing with the inflated number and nothing warned. An event whose description is\n      genuinely nothing but spaces cannot be told from fill, and inventing rows out of fill\n      is the worse of the two answers.\n    */\n    if ([...raw].every((c) => isPaddingByte(c.charCodeAt(0)))) continue;\n    annotations.push({\n      onset,\n      duration,\n      text: raw,\n      recordIndex,\n      ...(durationUnreadable ? { durationUnreadable: true } : {}),\n    });\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.js

@@ -122,7 +122,23 @@ export class EdfFile {
         if (!info.isFile()) {
             throw new EdfError('UNREADABLE', `"${path}" is not a regular file.`);
         }
-        const handle = await open(path, 'r');
+        /*
+          Opening is a second chance to be refused, and it was the one that got through.
+    
+          `stat` needs the parent directory searchable and says nothing about the file's own mode,
+          so a recording with no read permission passes it and fails here — the commonest
+          permission failure there is. Unwrapped, it escaped as Node's own error: the CLI printed
+          `error: EACCES: permission denied, open '...'` where every neighbouring failure prints
+          the tool's sentence, and the library threw a plain Error whose `code` was the errno.
+    
+          api.md says `UNREADABLE` "covers a missing file, a directory passed where a file was
+          expected, a permission failure, and a file that changed size while being read. Branch on
+          `code`, never on the message text." A consumer doing exactly that fell through to its
+          generic handler.
+        */
+        const handle = await open(path, 'r').catch((cause) => {
+            throw new EdfError('UNREADABLE', `Cannot read "${path}": ${describe(cause)}`);
+        });
         try {
             const fixed = Buffer.alloc(Math.min(FIXED_HEADER_BYTES, info.size));
             if (fixed.length > 0) {

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    /** How many of those also carried event text, so events were lost with the position. */\n    malformedTimekeepingWithText: 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 malformedTimekeepingWithText = 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        malformedTimekeepingWithText,\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        malformedTimekeepingWithText += decoded.malformedTimekeepingWithText;\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      malformedTimekeepingWithText,\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"]}
+{"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    /*\n      Opening is a second chance to be refused, and it was the one that got through.\n\n      `stat` needs the parent directory searchable and says nothing about the file's own mode,\n      so a recording with no read permission passes it and fails here — the commonest\n      permission failure there is. Unwrapped, it escaped as Node's own error: the CLI printed\n      `error: EACCES: permission denied, open '...'` where every neighbouring failure prints\n      the tool's sentence, and the library threw a plain Error whose `code` was the errno.\n\n      api.md says `UNREADABLE` \"covers a missing file, a directory passed where a file was\n      expected, a permission failure, and a file that changed size while being read. Branch on\n      `code`, never on the message text.\" A consumer doing exactly that fell through to its\n      generic handler.\n    */\n    const handle = await open(path, 'r').catch((cause: unknown) => {\n      throw new EdfError('UNREADABLE', `Cannot read \"${path}\": ${describe(cause)}`);\n    });\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    /** How many of those also carried event text, so events were lost with the position. */\n    malformedTimekeepingWithText: 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 malformedTimekeepingWithText = 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        malformedTimekeepingWithText,\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        malformedTimekeepingWithText += decoded.malformedTimekeepingWithText;\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      malformedTimekeepingWithText,\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.114",
+  "version": "0.5.116",
   "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",