edfcore 0.3.54 → 0.3.55

package/CHANGELOG.md

@@ -6,6 +6,29 @@ alone does not tell you whether you were affected.
 edfcore is pre-1.0. Patch releases have carried behaviour changes where the old behaviour was a
 defect; those are called out below.
 
+## 0.3.55
+
+- **Fixed** `streamRecords` never comparing record onsets across a chunk boundary, so an
+  always-fatal `TIMELINE_NOT_MONOTONIC` was suppressed and chunks were yielded in reverse time
+  order — and whether it fired at all depended on `chunkRecords`.
+  - `readRecords` runs `assertMonotonicOnsetArray` over the onsets of the chunk it just read, so
+    every adjacent pair **inside** a chunk is checked and no pair that straddles two is.
+    `readWindow` hands a whole contiguous run to one call, so it checks all of them; splitting the
+    same run into `chunkRecords`-sized reads checked none of the seams.
+  - On an eight-record file whose only backwards pair is 3 → 4, `readWindow` threw and
+    `streamRecords` threw at `chunkRecords` 3 and 5 while returning the data at 1, 2, 4 and 256.
+    At `chunkRecords: 1` **every** pair is a seam, so nothing was checked at all and the chunks came
+    back at 0, 1, 2, 4, 3, 5, 6, 7 seconds.
+  - `chunkRecords` is documented as "the unit of I/O and of memory". A performance knob must never
+    decide whether a file is refused — the fourth time that shape has been swept out of this
+    package.
+  - A consumer that places each chunk at its own `startSeconds`, which is what the docs prescribe,
+    silently overwrote earlier trace with later samples.
+- The seam check costs no extra read. A chunk's span is `lastOnset + recordDuration - firstOnset`,
+  so its last record's onset is `startTicks + durationTicks - recordDurationTicks`, already on the
+  same rebased axis as the next chunk's `startTicks`. It is reset per run, because `readWindow` does
+  not compare across a gap either and a streamed chunk must stay the object a read would give.
+
 ## 0.3.54
 
 - **Fixed** `decodeStatusWord` reading the BioSemi quality flags from the wrong bits. Both

package/dist/constants.d.ts

@@ -109,5 +109,5 @@ export declare const SIGNAL_FIELD_BLOCK_OFFSETS: {
     readonly reserved: 224;
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export declare const VERSION = "0.3.54";
+export declare const VERSION = "0.3.55";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -79,5 +79,5 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
     reserved: 224,
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.3.54';
+export const VERSION = '0.3.55';
 //# sourceMappingURL=constants.js.map

package/dist/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAe,eAAe,EAAE,MAAM,YAAY,CAAC;AAKpG;;;;;;;GAOG;AACH,wBAAuB,aAAa,CAClC,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE,WAAW,GACpB,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAyC3C"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAe,eAAe,EAAE,MAAM,YAAY,CAAC;AAKpG;;;;;;;GAOG;AACH,wBAAuB,aAAa,CAClC,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE,WAAW,GACpB,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,SAAS,CAAC,CAgF3C"}

package/dist/stream.js

@@ -13,6 +13,7 @@
  * `readWindow` chunk would, so a consumer sees the discontinuities rather than a smooth lie.
  */
 import { readRecords, resolveSignals } from './recording.js';
+import { assertMonotonicOnsets } from './time/timeline.js';
 import { resolveTimeWindow } from './time/window.js';
 /** How many records to read at a time when the caller does not say. */
 const DEFAULT_STREAM_RECORDS = 256;
@@ -38,8 +39,12 @@ export async function* streamRecords(recording, selection, options) {
     // Every other selection error in the package surfaces on the spot; this one waited for data.
     resolveSignals(recording.header, selection.signalIndices);
     const ranges = resolveTimeWindow(recording.timeline, recording.index, selection.startSeconds, selection.durationSeconds);
+    const recordDurationTicks = recording.header.recordDurationTicks;
     for (const run of ranges) {
         let scanned = 0;
+        // The last record of the previous chunk of THIS run. Reset per run, because `readWindow` does
+        // not compare across a gap either and a streamed chunk must be the same object it would get.
+        let previousRecord;
         while (scanned < run.count) {
             const records = {
                 start: run.start + scanned,
@@ -47,7 +52,38 @@ export async function* streamRecords(recording, selection, options) {
             };
             // readRecords, not a private path: the chunk a consumer gets from streaming and the chunk
             // it gets from reading must be the same object in every respect, including its diagnostics.
-            yield await readRecords(recording, { signalIndices: selection.signalIndices, records }, options);
+            const chunk = await readRecords(recording, { signalIndices: selection.signalIndices, records }, options);
+            /*
+             * The one pair `readRecords` structurally cannot see: the SEAM between two chunks.
+             *
+             * It runs `assertMonotonicOnsetArray` over the onsets of the chunk it just read, so every
+             * adjacent pair inside a chunk is compared and no pair that straddles two is. `readWindow`
+             * hands a whole contiguous run to one call and therefore checks all of them; splitting the
+             * same run into `chunkRecords`-sized reads checked none of the seams.
+             *
+             * TIMELINE_NOT_MONOTONIC is ALWAYS fatal — `readWindow` on the identical window throws —
+             * and the streaming path returned the data instead, in reverse time order: a consumer that
+             * places each chunk at its own `startSeconds`, which is what the docs prescribe, overwrote
+             * earlier trace with later samples. Worse, whether it fired at all depended on
+             * `chunkRecords`: on one eight-record file it threw at 3 and 5 and stayed silent at 1, 2, 4
+             * and 256, and `chunkRecords` is documented as a memory knob. A performance parameter must
+             * never decide whether a file is refused (fixed in 0.3.55).
+             *
+             * No extra read: a chunk's span is `lastOnset + recordDuration - firstOnset`, so its last
+             * record's onset is `startTicks + durationTicks - recordDurationTicks`, on the same rebased
+             * axis as the next chunk's `startTicks`.
+             */
+            if (previousRecord !== undefined) {
+                assertMonotonicOnsets(previousRecord, {
+                    recordIndex: records.start,
+                    onsetTicks: chunk.startTicks,
+                });
+            }
+            previousRecord = {
+                recordIndex: records.start + records.count - 1,
+                onsetTicks: chunk.startTicks + chunk.durationTicks - recordDurationTicks,
+            };
+            yield chunk;
             scanned += records.count;
         }
     }

package/dist/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,uEAAuE;AACvE,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,aAAa,CAClC,SAAuB,EACvB,SAA0B,EAC1B,OAAqB;IAErB,MAAM,YAAY,GAAG,SAAS,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACtE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,UAAU,CAClB,2EAA2E,YAAY,IAAI;YACzF,mFAAmF,CACtF,CAAC;IACJ,CAAC;IAED,+FAA+F;IAC/F,+FAA+F;IAC/F,2FAA2F;IAC3F,sFAAsF;IACtF,6FAA6F;IAC7F,6FAA6F;IAC7F,cAAc,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IAE1D,MAAM,MAAM,GAAG,iBAAiB,CAC9B,SAAS,CAAC,QAAQ,EAClB,SAAS,CAAC,KAAK,EACf,SAAS,CAAC,YAAY,EACtB,SAAS,CAAC,eAAe,CAC1B,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,OAAO,OAAO,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAgB;gBAC3B,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,OAAO;gBAC1B,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC;aACnD,CAAC;YACF,0FAA0F;YAC1F,4FAA4F;YAC5F,MAAM,MAAM,WAAW,CACrB,SAAS,EACT,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,EACnD,OAAO,CACR,CAAC;YACF,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,uEAAuE;AACvE,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,aAAa,CAClC,SAAuB,EACvB,SAA0B,EAC1B,OAAqB;IAErB,MAAM,YAAY,GAAG,SAAS,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACtE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,UAAU,CAClB,2EAA2E,YAAY,IAAI;YACzF,mFAAmF,CACtF,CAAC;IACJ,CAAC;IAED,+FAA+F;IAC/F,+FAA+F;IAC/F,2FAA2F;IAC3F,sFAAsF;IACtF,6FAA6F;IAC7F,6FAA6F;IAC7F,cAAc,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IAE1D,MAAM,MAAM,GAAG,iBAAiB,CAC9B,SAAS,CAAC,QAAQ,EAClB,SAAS,CAAC,KAAK,EACf,SAAS,CAAC,YAAY,EACtB,SAAS,CAAC,eAAe,CAC1B,CAAC;IAEF,MAAM,mBAAmB,GAAG,SAAS,CAAC,MAAM,CAAC,mBAAmB,CAAC;IAEjE,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,8FAA8F;QAC9F,6FAA6F;QAC7F,IAAI,cAAuE,CAAC;QAE5E,OAAO,OAAO,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAgB;gBAC3B,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,OAAO;gBAC1B,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC;aACnD,CAAC;YACF,0FAA0F;YAC1F,4FAA4F;YAC5F,MAAM,KAAK,GAAG,MAAM,WAAW,CAC7B,SAAS,EACT,EAAE,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,OAAO,EAAE,EACnD,OAAO,CACR,CAAC;YAEF;;;;;;;;;;;;;;;;;;;eAmBG;YACH,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,qBAAqB,CAAC,cAAc,EAAE;oBACpC,WAAW,EAAE,OAAO,CAAC,KAAK;oBAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;iBAC7B,CAAC,CAAC;YACL,CAAC;YACD,cAAc,GAAG;gBACf,WAAW,EAAE,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,GAAG,CAAC;gBAC9C,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,aAAa,GAAG,mBAAmB;aACzE,CAAC;YAEF,MAAM,KAAK,CAAC;YACZ,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC;QAC3B,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.3.54",
+  "version": "0.3.55",
   "description": "Modern, typed, zero-dependency reader for EDF, EDF+, BDF and BDF+ biosignal files. Works in browsers and Node with true random access.",
   "keywords": [
     "edf",

package/src/constants.ts

@@ -93,4 +93,4 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
 } as const;
 
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.3.54';
+export const VERSION = '0.3.55';

package/src/stream.ts

@@ -14,6 +14,7 @@
  */
 
 import { readRecords, resolveSignals } from './recording.js';
+import { assertMonotonicOnsets } from './time/timeline.js';
 import { resolveTimeWindow } from './time/window.js';
 import type { EdfChunk, EdfRecording, ReadOptions, RecordRange, StreamSelection } from './types.js';
 
@@ -56,8 +57,14 @@ export async function* streamRecords(
     selection.durationSeconds,
   );
 
+  const recordDurationTicks = recording.header.recordDurationTicks;
+
   for (const run of ranges) {
     let scanned = 0;
+    // The last record of the previous chunk of THIS run. Reset per run, because `readWindow` does
+    // not compare across a gap either and a streamed chunk must be the same object it would get.
+    let previousRecord: { recordIndex: number; onsetTicks: bigint } | undefined;
+
     while (scanned < run.count) {
       const records: RecordRange = {
         start: run.start + scanned,
@@ -65,11 +72,44 @@ export async function* streamRecords(
       };
       // readRecords, not a private path: the chunk a consumer gets from streaming and the chunk
       // it gets from reading must be the same object in every respect, including its diagnostics.
-      yield await readRecords(
+      const chunk = await readRecords(
         recording,
         { signalIndices: selection.signalIndices, records },
         options,
       );
+
+      /*
+       * The one pair `readRecords` structurally cannot see: the SEAM between two chunks.
+       *
+       * It runs `assertMonotonicOnsetArray` over the onsets of the chunk it just read, so every
+       * adjacent pair inside a chunk is compared and no pair that straddles two is. `readWindow`
+       * hands a whole contiguous run to one call and therefore checks all of them; splitting the
+       * same run into `chunkRecords`-sized reads checked none of the seams.
+       *
+       * TIMELINE_NOT_MONOTONIC is ALWAYS fatal — `readWindow` on the identical window throws —
+       * and the streaming path returned the data instead, in reverse time order: a consumer that
+       * places each chunk at its own `startSeconds`, which is what the docs prescribe, overwrote
+       * earlier trace with later samples. Worse, whether it fired at all depended on
+       * `chunkRecords`: on one eight-record file it threw at 3 and 5 and stayed silent at 1, 2, 4
+       * and 256, and `chunkRecords` is documented as a memory knob. A performance parameter must
+       * never decide whether a file is refused (fixed in 0.3.55).
+       *
+       * No extra read: a chunk's span is `lastOnset + recordDuration - firstOnset`, so its last
+       * record's onset is `startTicks + durationTicks - recordDurationTicks`, on the same rebased
+       * axis as the next chunk's `startTicks`.
+       */
+      if (previousRecord !== undefined) {
+        assertMonotonicOnsets(previousRecord, {
+          recordIndex: records.start,
+          onsetTicks: chunk.startTicks,
+        });
+      }
+      previousRecord = {
+        recordIndex: records.start + records.count - 1,
+        onsetTicks: chunk.startTicks + chunk.durationTicks - recordDurationTicks,
+      };
+
+      yield chunk;
       scanned += records.count;
     }
   }