edfcore 0.2.7 → 0.2.8

package/CHANGELOG.md

@@ -6,6 +6,17 @@ 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.2.8
+
+- **Added** `mergeChunks(chunks)`. `readWindow` splits at every discontinuity, and joining the
+  pieces by hand is where the gap gets lost: concatenating two runs five minutes apart dates every
+  sample after the join five minutes early, with nothing in the result to say so. This refuses,
+  and refuses a chunk already narrowed by `trimToWindow` too — that one is invisible to a record
+  adjacency check.
+- **Fixed** the 200,000-record call-stack test timing out under load. It ran within a few hundred
+  milliseconds of vitest's 5 s default on its own, so it failed intermittently in a full run and
+  the failure read as a regression in code it does not touch.
+
 ## 0.2.7
 
 - **Added** `edfcore gaps <file>`. Runs a full scan rather than reading the two probes `openEdf`

package/dist/chunks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Joining chunks that a read returned as several.
+ *
+ * Layer 7, and pure: nothing here reads. `readWindow` splits at every discontinuity, so a window
+ * over an EDF+D file comes back as one chunk per contiguous run. Code that then wants ONE array —
+ * a filter, an FFT, a CSV writer — has to join them, and joining is where the gap gets lost.
+ *
+ * Concatenating two runs separated by five minutes produces an array in which sample `i` and
+ * sample `i + 1` are five minutes apart. Every time derived from an index past that point is
+ * wrong by five minutes, and nothing in the result says so. `mergeChunks` refuses instead. A
+ * caller who genuinely wants the samples end to end can concatenate them in three lines and own
+ * the consequence; what they should not get is a helper that hides it.
+ *
+ * The refusals are caller mistakes, not file defects, so they are plain `RangeError`s — the same
+ * convention every option check in the package follows.
+ */
+import type { EdfChunk } from './types.js';
+/**
+ * One chunk covering every input chunk, or a `RangeError` explaining why they do not join.
+ *
+ * Accepts only chunks that are adjacent, in order, gapless, and read with the same signals in the
+ * same order. A single chunk is returned as-is, so the common continuous-file case costs nothing.
+ *
+ * The samples are copied, so the result holds a second copy of the data the inputs already hold.
+ * That is unavoidable — `Int32Array`s are not splices of one buffer — and it is why this is a
+ * separate call rather than something `readWindow` does on the way out.
+ */
+export declare function mergeChunks(chunks: readonly EdfChunk[]): EdfChunk;
+//# sourceMappingURL=chunks.d.ts.map

package/dist/chunks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../src/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAiC,MAAM,YAAY,CAAC;AA+D1E;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,QAAQ,CAwEjE"}

package/dist/chunks.js

@@ -0,0 +1,139 @@
+/**
+ * Joining chunks that a read returned as several.
+ *
+ * Layer 7, and pure: nothing here reads. `readWindow` splits at every discontinuity, so a window
+ * over an EDF+D file comes back as one chunk per contiguous run. Code that then wants ONE array —
+ * a filter, an FFT, a CSV writer — has to join them, and joining is where the gap gets lost.
+ *
+ * Concatenating two runs separated by five minutes produces an array in which sample `i` and
+ * sample `i + 1` are five minutes apart. Every time derived from an index past that point is
+ * wrong by five minutes, and nothing in the result says so. `mergeChunks` refuses instead. A
+ * caller who genuinely wants the samples end to end can concatenate them in three lines and own
+ * the consequence; what they should not get is a helper that hides it.
+ *
+ * The refusals are caller mistakes, not file defects, so they are plain `RangeError`s — the same
+ * convention every option check in the package follows.
+ */
+import { appendDiagnostics } from './diagnostics/collector.js';
+/** Reads as one line at the call site, and keeps the `chunks[i]` non-null assertions out of it. */
+function at(chunks, index) {
+    const chunk = chunks[index];
+    if (chunk === undefined)
+        throw new RangeError(`mergeChunks: no chunk at ${index}.`);
+    return chunk;
+}
+/**
+ * Everything that makes two chunks joinable, checked before a byte is allocated.
+ *
+ * The record-adjacency test is the obvious one. The per-signal sample-index test is the one that
+ * earns its place: `trimToWindow` narrows a chunk on each signal's own grid, so two chunks can
+ * still be record-adjacent after a trim has removed the samples between them. Comparing
+ * `firstSampleIndex` against the previous chunk's end catches exactly that, per signal, which is
+ * the granularity at which it actually happens.
+ */
+function assertJoinable(previous, next, index) {
+    if (next.precededByGap !== undefined) {
+        throw new RangeError(`mergeChunks: chunk ${index} is preceded by a gap of ${next.precededByGap.durationSeconds} s. ` +
+            'Concatenating across it would put two samples that are seconds apart next to each other ' +
+            'in one array, and every time computed from an index after the join would be wrong by the ' +
+            'gap. Merge each contiguous run separately.');
+    }
+    const expectedStart = previous.records.start + previous.records.count;
+    if (next.records.start !== expectedStart) {
+        throw new RangeError(`mergeChunks: chunk ${index} starts at record ${next.records.start}, but the chunk before ` +
+            `it ends at ${expectedStart}. Chunks must be adjacent and in order.`);
+    }
+    if (next.signals.length !== previous.signals.length) {
+        throw new RangeError(`mergeChunks: chunk ${index} carries ${next.signals.length} signal(s), the chunk before it ` +
+            `${previous.signals.length}. Every chunk must have been read with the same signal selection.`);
+    }
+    for (let i = 0; i < next.signals.length; i += 1) {
+        const before = previous.signals[i];
+        const after = next.signals[i];
+        if (after.signalIndex !== before.signalIndex) {
+            throw new RangeError(`mergeChunks: chunk ${index} has signal ${after.signalIndex} in position ${i}, the chunk ` +
+                `before it signal ${before.signalIndex}. The selection must be in the same order too.`);
+        }
+        const expectedSample = before.firstSampleIndex + before.sampleCount;
+        if (after.firstSampleIndex !== expectedSample) {
+            throw new RangeError(`mergeChunks: signal ${after.signalIndex} of chunk ${index} starts at sample ` +
+                `${after.firstSampleIndex}, but the chunk before it ends at ${expectedSample}. ` +
+                'A trimmed chunk cannot be merged with the one after it — trim after merging, not before.');
+        }
+    }
+}
+/**
+ * One chunk covering every input chunk, or a `RangeError` explaining why they do not join.
+ *
+ * Accepts only chunks that are adjacent, in order, gapless, and read with the same signals in the
+ * same order. A single chunk is returned as-is, so the common continuous-file case costs nothing.
+ *
+ * The samples are copied, so the result holds a second copy of the data the inputs already hold.
+ * That is unavoidable — `Int32Array`s are not splices of one buffer — and it is why this is a
+ * separate call rather than something `readWindow` does on the way out.
+ */
+export function mergeChunks(chunks) {
+    if (chunks.length === 0) {
+        throw new RangeError('mergeChunks: nothing to merge. `readWindow` returns [] for a window that lands past the ' +
+            'end of the recording, so check the length before merging.');
+    }
+    const first = at(chunks, 0);
+    if (chunks.length === 1)
+        return first;
+    for (let i = 1; i < chunks.length; i += 1) {
+        assertJoinable(at(chunks, i - 1), at(chunks, i), i);
+    }
+    const last = at(chunks, chunks.length - 1);
+    const signals = first.signals.map((firstSignal, position) => {
+        let total = 0;
+        let outOfRange = 0;
+        for (const chunk of chunks) {
+            const signal = chunk.signals[position];
+            total += signal.sampleCount;
+            outOfRange += signal.outOfDigitalRangeCount;
+        }
+        const digital = new Int32Array(total);
+        let written = 0;
+        for (const chunk of chunks) {
+            const signal = chunk.signals[position];
+            // `digital` may be longer than `sampleCount` — the decoder is allowed to hand back a buffer
+            // it sized for whole records. `sampleCount` is the truth, so the subarray is taken from it.
+            digital.set(signal.digital.subarray(0, signal.sampleCount), written);
+            written += signal.sampleCount;
+        }
+        return {
+            signalIndex: firstSignal.signalIndex,
+            sampleCount: total,
+            digital,
+            firstSampleIndex: firstSignal.firstSampleIndex,
+            startSeconds: firstSignal.startSeconds,
+            outOfDigitalRangeCount: outOfRange,
+        };
+    });
+    let byteLength = 0;
+    const diagnostics = [];
+    for (const chunk of chunks) {
+        byteLength += chunk.byteLength;
+        // Not `push(...chunk.diagnostics)`: a scan over a damaged annotation section reports one
+        // diagnostic per record, and the spread blows the call stack past ~125,000 of them (0.1.6).
+        appendDiagnostics(diagnostics, chunk.diagnostics);
+    }
+    return {
+        records: {
+            start: first.records.start,
+            count: last.records.start + last.records.count - first.records.start,
+        },
+        startSeconds: first.startSeconds,
+        // Two float operations against the ends, not a sum of N durations: adding the durations up
+        // accumulates rounding once per chunk, and the run is contiguous so the ends are the truth.
+        durationSeconds: last.startSeconds + last.durationSeconds - first.startSeconds,
+        byteOffset: first.byteOffset,
+        byteLength,
+        signals: Object.freeze(signals),
+        // The gap BEFORE the whole run survives the merge. It describes what precedes the first
+        // chunk, which is still what precedes the merged one.
+        precededByGap: first.precededByGap,
+        diagnostics: Object.freeze(diagnostics),
+    };
+}
+//# sourceMappingURL=chunks.js.map

package/dist/chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.js","sourceRoot":"","sources":["../src/chunks.ts"],"names":[],"mappings":"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"}

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.2.7";
+export declare const VERSION = "0.2.8";
 //# 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.2.7';
+export const VERSION = '0.2.8';
 //# sourceMappingURL=constants.js.map

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export { readHeader, readRecordBytes } from './io/read.js';
 export { buildRecordIndex, buildTimeline, contiguityOf } from './record-index.js';
 export { annotationsAt, countAnnotationsByText, filterAnnotationsByText, filterAnnotationsByTime, } from './annotations-query.js';
 export { decodeStatusWord, getStatusSignal, readTriggers } from './biosemi.js';
+export { mergeChunks } from './chunks.js';
 export { envelopeOfSamples, readEnvelope, readEnvelopeAtResolution, toPhysicalEnvelope, } from './envelope.js';
 export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -56,6 +56,7 @@ export { buildRecordIndex, buildTimeline, contiguityOf } from './record-index.js
 // ===========================================================================
 export { annotationsAt, countAnnotationsByText, filterAnnotationsByText, filterAnnotationsByTime, } from './annotations-query.js';
 export { decodeStatusWord, getStatusSignal, readTriggers } from './biosemi.js';
+export { mergeChunks } from './chunks.js';
 export { envelopeOfSamples, readEnvelope, readEnvelopeAtResolution, toPhysicalEnvelope, } from './envelope.js';
 export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0EH,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,OAAO,GACR,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAC9E,2EAA2E;AAC3E,2CAA2C;AAC3C,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,6CAA6C;AAC7C,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElF,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0EH,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,OAAO,GACR,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAC9E,2EAA2E;AAC3E,2CAA2C;AAC3C,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,6CAA6C;AAC7C,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElF,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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/chunks.ts

@@ -0,0 +1,164 @@
+/**
+ * Joining chunks that a read returned as several.
+ *
+ * Layer 7, and pure: nothing here reads. `readWindow` splits at every discontinuity, so a window
+ * over an EDF+D file comes back as one chunk per contiguous run. Code that then wants ONE array —
+ * a filter, an FFT, a CSV writer — has to join them, and joining is where the gap gets lost.
+ *
+ * Concatenating two runs separated by five minutes produces an array in which sample `i` and
+ * sample `i + 1` are five minutes apart. Every time derived from an index past that point is
+ * wrong by five minutes, and nothing in the result says so. `mergeChunks` refuses instead. A
+ * caller who genuinely wants the samples end to end can concatenate them in three lines and own
+ * the consequence; what they should not get is a helper that hides it.
+ *
+ * The refusals are caller mistakes, not file defects, so they are plain `RangeError`s — the same
+ * convention every option check in the package follows.
+ */
+
+import { appendDiagnostics } from './diagnostics/collector.js';
+import type { EdfChunk, EdfChunkSignal, EdfDiagnostic } from './types.js';
+
+/** Reads as one line at the call site, and keeps the `chunks[i]` non-null assertions out of it. */
+function at(chunks: readonly EdfChunk[], index: number): EdfChunk {
+  const chunk = chunks[index];
+  if (chunk === undefined) throw new RangeError(`mergeChunks: no chunk at ${index}.`);
+  return chunk;
+}
+
+/**
+ * Everything that makes two chunks joinable, checked before a byte is allocated.
+ *
+ * The record-adjacency test is the obvious one. The per-signal sample-index test is the one that
+ * earns its place: `trimToWindow` narrows a chunk on each signal's own grid, so two chunks can
+ * still be record-adjacent after a trim has removed the samples between them. Comparing
+ * `firstSampleIndex` against the previous chunk's end catches exactly that, per signal, which is
+ * the granularity at which it actually happens.
+ */
+function assertJoinable(previous: EdfChunk, next: EdfChunk, index: number): void {
+  if (next.precededByGap !== undefined) {
+    throw new RangeError(
+      `mergeChunks: chunk ${index} is preceded by a gap of ${next.precededByGap.durationSeconds} s. ` +
+        'Concatenating across it would put two samples that are seconds apart next to each other ' +
+        'in one array, and every time computed from an index after the join would be wrong by the ' +
+        'gap. Merge each contiguous run separately.',
+    );
+  }
+
+  const expectedStart = previous.records.start + previous.records.count;
+  if (next.records.start !== expectedStart) {
+    throw new RangeError(
+      `mergeChunks: chunk ${index} starts at record ${next.records.start}, but the chunk before ` +
+        `it ends at ${expectedStart}. Chunks must be adjacent and in order.`,
+    );
+  }
+
+  if (next.signals.length !== previous.signals.length) {
+    throw new RangeError(
+      `mergeChunks: chunk ${index} carries ${next.signals.length} signal(s), the chunk before it ` +
+        `${previous.signals.length}. Every chunk must have been read with the same signal selection.`,
+    );
+  }
+
+  for (let i = 0; i < next.signals.length; i += 1) {
+    const before = previous.signals[i] as EdfChunkSignal;
+    const after = next.signals[i] as EdfChunkSignal;
+    if (after.signalIndex !== before.signalIndex) {
+      throw new RangeError(
+        `mergeChunks: chunk ${index} has signal ${after.signalIndex} in position ${i}, the chunk ` +
+          `before it signal ${before.signalIndex}. The selection must be in the same order too.`,
+      );
+    }
+    const expectedSample = before.firstSampleIndex + before.sampleCount;
+    if (after.firstSampleIndex !== expectedSample) {
+      throw new RangeError(
+        `mergeChunks: signal ${after.signalIndex} of chunk ${index} starts at sample ` +
+          `${after.firstSampleIndex}, but the chunk before it ends at ${expectedSample}. ` +
+          'A trimmed chunk cannot be merged with the one after it — trim after merging, not before.',
+      );
+    }
+  }
+}
+
+/**
+ * One chunk covering every input chunk, or a `RangeError` explaining why they do not join.
+ *
+ * Accepts only chunks that are adjacent, in order, gapless, and read with the same signals in the
+ * same order. A single chunk is returned as-is, so the common continuous-file case costs nothing.
+ *
+ * The samples are copied, so the result holds a second copy of the data the inputs already hold.
+ * That is unavoidable — `Int32Array`s are not splices of one buffer — and it is why this is a
+ * separate call rather than something `readWindow` does on the way out.
+ */
+export function mergeChunks(chunks: readonly EdfChunk[]): EdfChunk {
+  if (chunks.length === 0) {
+    throw new RangeError(
+      'mergeChunks: nothing to merge. `readWindow` returns [] for a window that lands past the ' +
+        'end of the recording, so check the length before merging.',
+    );
+  }
+
+  const first = at(chunks, 0);
+  if (chunks.length === 1) return first;
+
+  for (let i = 1; i < chunks.length; i += 1) {
+    assertJoinable(at(chunks, i - 1), at(chunks, i), i);
+  }
+
+  const last = at(chunks, chunks.length - 1);
+
+  const signals = first.signals.map((firstSignal, position) => {
+    let total = 0;
+    let outOfRange = 0;
+    for (const chunk of chunks) {
+      const signal = chunk.signals[position] as EdfChunkSignal;
+      total += signal.sampleCount;
+      outOfRange += signal.outOfDigitalRangeCount;
+    }
+
+    const digital = new Int32Array(total);
+    let written = 0;
+    for (const chunk of chunks) {
+      const signal = chunk.signals[position] as EdfChunkSignal;
+      // `digital` may be longer than `sampleCount` — the decoder is allowed to hand back a buffer
+      // it sized for whole records. `sampleCount` is the truth, so the subarray is taken from it.
+      digital.set(signal.digital.subarray(0, signal.sampleCount), written);
+      written += signal.sampleCount;
+    }
+
+    return {
+      signalIndex: firstSignal.signalIndex,
+      sampleCount: total,
+      digital,
+      firstSampleIndex: firstSignal.firstSampleIndex,
+      startSeconds: firstSignal.startSeconds,
+      outOfDigitalRangeCount: outOfRange,
+    } satisfies EdfChunkSignal;
+  });
+
+  let byteLength = 0;
+  const diagnostics: EdfDiagnostic[] = [];
+  for (const chunk of chunks) {
+    byteLength += chunk.byteLength;
+    // Not `push(...chunk.diagnostics)`: a scan over a damaged annotation section reports one
+    // diagnostic per record, and the spread blows the call stack past ~125,000 of them (0.1.6).
+    appendDiagnostics(diagnostics, chunk.diagnostics);
+  }
+
+  return {
+    records: {
+      start: first.records.start,
+      count: last.records.start + last.records.count - first.records.start,
+    },
+    startSeconds: first.startSeconds,
+    // Two float operations against the ends, not a sum of N durations: adding the durations up
+    // accumulates rounding once per chunk, and the run is contiguous so the ends are the truth.
+    durationSeconds: last.startSeconds + last.durationSeconds - first.startSeconds,
+    byteOffset: first.byteOffset,
+    byteLength,
+    signals: Object.freeze(signals),
+    // The gap BEFORE the whole run survives the merge. It describes what precedes the first
+    // chunk, which is still what precedes the merged one.
+    precededByGap: first.precededByGap,
+    diagnostics: Object.freeze(diagnostics),
+  };
+}

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.2.7';
+export const VERSION = '0.2.8';

package/src/index.ts

@@ -171,6 +171,7 @@ export {
   filterAnnotationsByTime,
 } from './annotations-query.js';
 export { decodeStatusWord, getStatusSignal, readTriggers } from './biosemi.js';
+export { mergeChunks } from './chunks.js';
 export {
   envelopeOfSamples,
   readEnvelope,