edfcore 0.1.0

package/dist/time/window.js

@@ -0,0 +1,232 @@
+/**
+ * Windows in seconds, resolved to records and then to samples.
+ *
+ * Layer 4. Pure and synchronous, both halves of it. `resolveTimeWindow` answers "which records
+ * does this window cost?" before a byte is read, so the price of a window is auditable rather
+ * than discovered; `trimToWindow` narrows a record-aligned chunk to the samples actually asked
+ * for.
+ *
+ * The window is the half-open interval `[startSeconds, startSeconds + durationSeconds)` in
+ * elapsed recording time — `t = 0` is the start of record 0, the axis `time/timeline.ts` fixes.
+ *
+ * Every comparison below is integer or rational arithmetic on ticks, records and
+ * `samplesPerRecord`. `round(t * sampleRateHz)` appears nowhere: `sampleRateHz` is derived and
+ * often not representable (256/3 Hz is a real record duration of 3 s with 256 samples), so
+ * rounding through it walks the answer off by a sample near every large `t` — which is the exact
+ * mistake edfcore exists to stop a consumer from re-implementing.
+ */
+import { TICKS_PER_SECOND } from '../constants.js';
+import { EdfChannelNotFoundError } from '../errors.js';
+import { secondsToTicks, ticksToSeconds } from '../tal/ticks.js';
+const NO_RANGES = Object.freeze([]);
+/** Exact: 10^7 is far below 2^53. */
+const TICKS_PER_SECOND_FLOAT = Number(TICKS_PER_SECOND);
+/** `b` must be positive. Bigint `/` truncates toward zero, so negatives need the correction. */
+function floorDiv(a, b) {
+    const quotient = a / b;
+    return a % b === 0n || a > 0n ? quotient : quotient - 1n;
+}
+function ceilDiv(a, b) {
+    const quotient = a / b;
+    return a % b === 0n || a < 0n ? quotient : quotient + 1n;
+}
+/** Clamping in bigint first, because `Number()` on a large bigint silently loses digits. */
+function clampToInt(value, low, high) {
+    if (value <= BigInt(low))
+        return low;
+    if (value >= BigInt(high))
+        return high;
+    return Number(value);
+}
+/**
+ * The record duration in exact ticks, recovered from the timeline's float.
+ *
+ * `resolveTimeWindow`'s signature takes no header, so `header.recordDurationTicks` is not
+ * available here. The round-trip is exact anyway: the seconds value was itself produced from a
+ * header field of at most a few decimals, and `secondsToTicks` rounds to the nearest tick, so
+ * every duration a file can declare below ~10^9 s comes back to the tick it came from.
+ */
+function recordDurationTicksOf(timeline) {
+    return secondsToTicks(timeline.recordDurationSeconds);
+}
+function signalAt(header, signalIndex) {
+    const signal = header.signals[signalIndex];
+    if (signal !== undefined)
+        return signal;
+    throw new EdfChannelNotFoundError(`signalIndex ${signalIndex} is not one of the ${header.signals.length} signals in this ` +
+        'header, so trimToWindow() cannot know how many samples per record it holds. Next: pass ' +
+        'the header the chunk was read with.', { selector: signalIndex, availableLabels: header.signals.map((s) => s.label) });
+}
+/**
+ * The records a window needs, one `RecordRange` per contiguous run it overlaps, in time order.
+ *
+ * Empty when the window falls entirely inside a gap, entirely outside the recording, or has a
+ * non-positive duration — the interval is half-open, so a zero-length window contains no time
+ * and therefore no samples.
+ *
+ * Ranges are RECORD-ALIGNED and are therefore usually wider than the window: a record is the
+ * smallest unit the file can be read by, and `trimToWindow` is how a caller narrows the samples
+ * afterwards.
+ *
+ * With `index.segments` present (`coverage === 'complete'`) the answer is exact. With a probed
+ * index it is exact only while the file is contiguous, which is precisely what
+ * `spanSeconds === coveredSeconds` states; when it is not, the records a window maps to depend
+ * on onsets nobody has read, and this function refuses rather than guessing them.
+ */
+export function resolveTimeWindow(timeline, index, startSeconds, durationSeconds) {
+    const recordCount = timeline.recordCount;
+    if (recordCount <= 0)
+        return NO_RANGES;
+    const windowStartTicks = secondsToTicks(startSeconds);
+    const windowDurationTicks = secondsToTicks(durationSeconds);
+    if (windowDurationTicks <= 0n)
+        return NO_RANGES;
+    const windowEndTicks = windowStartTicks + windowDurationTicks;
+    const durationTicks = recordDurationTicksOf(timeline);
+    const segments = index.segments;
+    if (segments !== undefined) {
+        const ranges = [];
+        for (const segment of segments) {
+            const segmentCount = segment.records.count;
+            if (segmentCount <= 0)
+                continue;
+            const segmentStartTicks = segment.startTicks;
+            // A zero record duration puts every record of the segment at one instant, so the segment
+            // is either wholly inside the window or wholly outside it.
+            if (durationTicks === 0n) {
+                if (windowStartTicks <= segmentStartTicks && segmentStartTicks < windowEndTicks) {
+                    ranges.push({ start: segment.records.start, count: segmentCount });
+                }
+                continue;
+            }
+            const segmentEndTicks = segmentStartTicks + BigInt(segmentCount) * durationTicks;
+            if (segmentEndTicks <= windowStartTicks || segmentStartTicks >= windowEndTicks)
+                continue;
+            const firstOffset = clampToInt(floorDiv(windowStartTicks - segmentStartTicks, durationTicks), 0, segmentCount - 1);
+            const lastOffset = clampToInt(ceilDiv(windowEndTicks - segmentStartTicks, durationTicks) - 1n, 0, segmentCount - 1);
+            if (lastOffset < firstOffset)
+                continue;
+            ranges.push({
+                start: segment.records.start + firstOffset,
+                count: lastOffset - firstOffset + 1,
+            });
+        }
+        return Object.freeze(ranges);
+    }
+    if (timeline.spanSeconds !== timeline.coveredSeconds) {
+        throw new RangeError(`resolveTimeWindow() cannot map seconds to records on this file: its ${recordCount} ` +
+            `records span ${timeline.spanSeconds} s but cover only ${timeline.coveredSeconds} s, so ` +
+            'it contains at least one gap, and a probed index knows where neither the gap nor the ' +
+            'records after it start. Next: await buildRecordIndex(recording) and pass the index it ' +
+            'returns, or locate the window with index.locate(seconds).');
+    }
+    // Contiguous as far as the probes can tell: record r starts at exactly r * recordDuration.
+    if (durationTicks === 0n) {
+        return windowStartTicks <= 0n && windowEndTicks > 0n
+            ? Object.freeze([{ start: 0, count: recordCount }])
+            : NO_RANGES;
+    }
+    if (windowEndTicks <= 0n)
+        return NO_RANGES;
+    if (windowStartTicks >= BigInt(recordCount) * durationTicks)
+        return NO_RANGES;
+    const first = clampToInt(floorDiv(windowStartTicks, durationTicks), 0, recordCount - 1);
+    const last = clampToInt(ceilDiv(windowEndTicks, durationTicks) - 1n, 0, recordCount - 1);
+    if (last < first)
+        return NO_RANGES;
+    return Object.freeze([{ start: first, count: last - first + 1 }]);
+}
+/**
+ * Sample `firstIndex` of the chunk, in seconds, as an exact rational.
+ *
+ * The sample sits at `chunkStart + firstIndex * recordDuration / samplesPerRecord`, and that
+ * division is usually not a whole number of ticks. The whole part goes through `ticksToSeconds`
+ * and only the remainder is divided, so the sub-tick part costs one rounding instead of poisoning
+ * the seconds and the ticks together. Bigint `/` and `%` agree in sign, so a negative chunk start
+ * (a pre-stimulus window) sums correctly.
+ */
+function sampleStartSeconds(chunkStartTicks, firstIndex, durationTicks, samplesPerRecord) {
+    const scaled = chunkStartTicks * samplesPerRecord + firstIndex * durationTicks;
+    const wholeTicks = scaled / samplesPerRecord;
+    const remainder = scaled % samplesPerRecord;
+    return (ticksToSeconds(wholeTicks) +
+        Number(remainder) / (Number(samplesPerRecord) * TICKS_PER_SECOND_FLOAT));
+}
+function countOutOfDigitalRange(digital, signal) {
+    const low = Math.min(signal.digitalMinimum, signal.digitalMaximum);
+    const high = Math.max(signal.digitalMinimum, signal.digitalMaximum);
+    let count = 0;
+    for (let i = 0; i < digital.length; i += 1) {
+        // biome-ignore lint/style/noNonNullAssertion: i is bounded by digital.length.
+        const value = digital[i];
+        if (value < low || value > high)
+            count += 1;
+    }
+    return count;
+}
+function trimmed(chunkSignal, signal, firstIndex, sampleCount, startSeconds) {
+    const digital = chunkSignal.digital.subarray(firstIndex, firstIndex + sampleCount);
+    const keptEverything = firstIndex === 0 && digital.length === chunkSignal.digital.length;
+    return {
+        signalIndex: chunkSignal.signalIndex,
+        // From the view, so the count and the data cannot disagree even if the chunk they came from
+        // declared a length its array did not have.
+        sampleCount: digital.length,
+        digital,
+        firstSampleIndex: chunkSignal.firstSampleIndex + firstIndex,
+        startSeconds,
+        // Re-counted only when it can have changed and only when there is something to find: a
+        // chunk with no out-of-range samples cannot acquire one by being narrowed.
+        outOfDigitalRangeCount: keptEverything || chunkSignal.outOfDigitalRangeCount === 0
+            ? chunkSignal.outOfDigitalRangeCount
+            : countOutOfDigitalRange(digital, signal),
+    };
+}
+/**
+ * The exact per-signal trim of a record-aligned chunk to `[startSeconds, startSeconds + duration)`.
+ *
+ * Sample `j` of the chunk starts at `chunkSignal.startSeconds + j * recordDuration /
+ * samplesPerRecord`, so the samples inside the window are those with
+ * `j * recordDuration >= relativeStart * samplesPerRecord` and
+ * `j * recordDuration < relativeEnd * samplesPerRecord`. Both comparisons are integer bigint
+ * products of on-disk quantities — no division, no sample rate, no float bound — which is what
+ * makes the boundary sample the same one every time and on every platform.
+ *
+ * The chunk must be one contiguous run of records (what `readWindow` returns), because that is
+ * what makes the sample grid uniform across it.
+ *
+ * `digital` in the result is a SUBARRAY view of the input's, so trimming allocates nothing and
+ * the two share memory. A window that only partly overlaps the chunk is clamped to the samples
+ * that exist; one that misses it entirely yields a zero-length result rather than an error.
+ */
+export function trimToWindow(header, chunkSignal, startSeconds, durationSeconds) {
+    const signal = signalAt(header, chunkSignal.signalIndex);
+    const samplesPerRecord = signal.samplesPerRecord;
+    const durationTicks = header.recordDurationTicks;
+    const available = Math.min(chunkSignal.sampleCount, chunkSignal.digital.length);
+    const windowStartTicks = secondsToTicks(startSeconds);
+    const windowDurationTicks = secondsToTicks(durationSeconds);
+    // The chunk's own start is a float only because `EdfChunkSignal` publishes seconds; it was
+    // produced from exact ticks by `ticksToSeconds`, and rounding back to the nearest tick recovers
+    // them for any recording shorter than ~28.5 years.
+    const chunkStartTicks = secondsToTicks(chunkSignal.startSeconds);
+    // Nothing advances in time within the chunk: a zero record duration puts every sample at the
+    // chunk's start instant, and a signal with no samples per record has no grid at all. The chunk
+    // is then either wholly inside the window or wholly outside it.
+    if (durationTicks === 0n || samplesPerRecord === 0) {
+        const inside = windowDurationTicks > 0n &&
+            windowStartTicks <= chunkStartTicks &&
+            chunkStartTicks < windowStartTicks + windowDurationTicks;
+        return inside
+            ? trimmed(chunkSignal, signal, 0, available, chunkSignal.startSeconds)
+            : trimmed(chunkSignal, signal, 0, 0, chunkSignal.startSeconds);
+    }
+    const samplesPerRecordTicks = BigInt(samplesPerRecord);
+    const relativeStartTicks = windowStartTicks - chunkStartTicks;
+    const relativeEndTicks = relativeStartTicks + windowDurationTicks;
+    const firstIndex = clampToInt(ceilDiv(relativeStartTicks * samplesPerRecordTicks, durationTicks), 0, available);
+    const lastIndex = clampToInt(ceilDiv(relativeEndTicks * samplesPerRecordTicks, durationTicks) - 1n, -1, available - 1);
+    const sampleCount = lastIndex < firstIndex ? 0 : lastIndex - firstIndex + 1;
+    return trimmed(chunkSignal, signal, firstIndex, sampleCount, sampleStartSeconds(chunkStartTicks, BigInt(firstIndex), durationTicks, samplesPerRecordTicks));
+}
+//# sourceMappingURL=window.js.map

package/dist/time/window.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.js","sourceRoot":"","sources":["../../src/time/window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAUjE,MAAM,SAAS,GAA2B,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE5D,qCAAqC;AACrC,MAAM,sBAAsB,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAExD,gGAAgG;AAChG,SAAS,QAAQ,CAAC,CAAS,EAAE,CAAS;IACpC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,OAAO,CAAC,CAAS,EAAE,CAAS;IACnC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,GAAG,EAAE,CAAC;AAC3D,CAAC;AAED,4FAA4F;AAC5F,SAAS,UAAU,CAAC,KAAa,EAAE,GAAW,EAAE,IAAY;IAC1D,IAAI,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACrC,IAAI,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,qBAAqB,CAAC,QAAqB;IAClD,OAAO,cAAc,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,QAAQ,CAAC,MAAiB,EAAE,WAAmB;IACtD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,IAAI,uBAAuB,CAC/B,eAAe,WAAW,sBAAsB,MAAM,CAAC,OAAO,CAAC,MAAM,mBAAmB;QACtF,yFAAyF;QACzF,qCAAqC,EACvC,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAC/E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAqB,EACrB,KAAqB,EACrB,YAAoB,EACpB,eAAuB;IAEvB,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC;IACzC,IAAI,WAAW,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAEvC,MAAM,gBAAgB,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACtD,MAAM,mBAAmB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAC5D,IAAI,mBAAmB,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,cAAc,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;IAE9D,MAAM,aAAa,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAkB,EAAE,CAAC;QACjC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC;YAC3C,IAAI,YAAY,IAAI,CAAC;gBAAE,SAAS;YAChC,MAAM,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;YAE7C,yFAAyF;YACzF,2DAA2D;YAC3D,IAAI,aAAa,KAAK,EAAE,EAAE,CAAC;gBACzB,IAAI,gBAAgB,IAAI,iBAAiB,IAAI,iBAAiB,GAAG,cAAc,EAAE,CAAC;oBAChF,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;gBACrE,CAAC;gBACD,SAAS;YACX,CAAC;YAED,MAAM,eAAe,GAAG,iBAAiB,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,aAAa,CAAC;YACjF,IAAI,eAAe,IAAI,gBAAgB,IAAI,iBAAiB,IAAI,cAAc;gBAAE,SAAS;YAEzF,MAAM,WAAW,GAAG,UAAU,CAC5B,QAAQ,CAAC,gBAAgB,GAAG,iBAAiB,EAAE,aAAa,CAAC,EAC7D,CAAC,EACD,YAAY,GAAG,CAAC,CACjB,CAAC;YACF,MAAM,UAAU,GAAG,UAAU,CAC3B,OAAO,CAAC,cAAc,GAAG,iBAAiB,EAAE,aAAa,CAAC,GAAG,EAAE,EAC/D,CAAC,EACD,YAAY,GAAG,CAAC,CACjB,CAAC;YACF,IAAI,UAAU,GAAG,WAAW;gBAAE,SAAS;YACvC,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,GAAG,WAAW;gBAC1C,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,CAAC;aACpC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,QAAQ,CAAC,WAAW,KAAK,QAAQ,CAAC,cAAc,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAClB,uEAAuE,WAAW,GAAG;YACnF,gBAAgB,QAAQ,CAAC,WAAW,qBAAqB,QAAQ,CAAC,cAAc,SAAS;YACzF,uFAAuF;YACvF,wFAAwF;YACxF,2DAA2D,CAC9D,CAAC;IACJ,CAAC;IAED,2FAA2F;IAC3F,IAAI,aAAa,KAAK,EAAE,EAAE,CAAC;QACzB,OAAO,gBAAgB,IAAI,EAAE,IAAI,cAAc,GAAG,EAAE;YAClD,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;YACnD,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IACD,IAAI,cAAc,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,gBAAgB,IAAI,MAAM,CAAC,WAAW,CAAC,GAAG,aAAa;QAAE,OAAO,SAAS,CAAC;IAC9E,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,CAAC,gBAAgB,EAAE,aAAa,CAAC,EAAE,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC;IACxF,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,cAAc,EAAE,aAAa,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,CAAC;IACzF,IAAI,IAAI,GAAG,KAAK;QAAE,OAAO,SAAS,CAAC;IACnC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CACzB,eAAuB,EACvB,UAAkB,EAClB,aAAqB,EACrB,gBAAwB;IAExB,MAAM,MAAM,GAAG,eAAe,GAAG,gBAAgB,GAAG,UAAU,GAAG,aAAa,CAAC;IAC/E,MAAM,UAAU,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAC7C,MAAM,SAAS,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAC5C,OAAO,CACL,cAAc,CAAC,UAAU,CAAC;QAC1B,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG,sBAAsB,CAAC,CACxE,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,OAAmB,EAAE,MAAiB;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;IACnE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC;IACpE,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,8EAA8E;QAC9E,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;QAC1B,IAAI,KAAK,GAAG,GAAG,IAAI,KAAK,GAAG,IAAI;YAAE,KAAK,IAAI,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CACd,WAA2B,EAC3B,MAAiB,EACjB,UAAkB,EAClB,WAAmB,EACnB,YAAoB;IAEpB,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW,CAAC,CAAC;IACnF,MAAM,cAAc,GAAG,UAAU,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;IACzF,OAAO;QACL,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,4FAA4F;QAC5F,4CAA4C;QAC5C,WAAW,EAAE,OAAO,CAAC,MAAM;QAC3B,OAAO;QACP,gBAAgB,EAAE,WAAW,CAAC,gBAAgB,GAAG,UAAU;QAC3D,YAAY;QACZ,uFAAuF;QACvF,2EAA2E;QAC3E,sBAAsB,EACpB,cAAc,IAAI,WAAW,CAAC,sBAAsB,KAAK,CAAC;YACxD,CAAC,CAAC,WAAW,CAAC,sBAAsB;YACpC,CAAC,CAAC,sBAAsB,CAAC,OAAO,EAAE,MAAM,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAiB,EACjB,WAA2B,EAC3B,YAAoB,EACpB,eAAuB;IAEvB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACzD,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACjD,MAAM,aAAa,GAAG,MAAM,CAAC,mBAAmB,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,WAAW,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAEhF,MAAM,gBAAgB,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IACtD,MAAM,mBAAmB,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IAC5D,2FAA2F;IAC3F,gGAAgG;IAChG,mDAAmD;IACnD,MAAM,eAAe,GAAG,cAAc,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAEjE,6FAA6F;IAC7F,+FAA+F;IAC/F,gEAAgE;IAChE,IAAI,aAAa,KAAK,EAAE,IAAI,gBAAgB,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,MAAM,GACV,mBAAmB,GAAG,EAAE;YACxB,gBAAgB,IAAI,eAAe;YACnC,eAAe,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;QAC3D,OAAO,MAAM;YACX,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,WAAW,CAAC,YAAY,CAAC;YACtE,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,qBAAqB,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACvD,MAAM,kBAAkB,GAAG,gBAAgB,GAAG,eAAe,CAAC;IAC9D,MAAM,gBAAgB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IAElE,MAAM,UAAU,GAAG,UAAU,CAC3B,OAAO,CAAC,kBAAkB,GAAG,qBAAqB,EAAE,aAAa,CAAC,EAClE,CAAC,EACD,SAAS,CACV,CAAC;IACF,MAAM,SAAS,GAAG,UAAU,CAC1B,OAAO,CAAC,gBAAgB,GAAG,qBAAqB,EAAE,aAAa,CAAC,GAAG,EAAE,EACrE,CAAC,CAAC,EACF,SAAS,GAAG,CAAC,CACd,CAAC;IACF,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,UAAU,GAAG,CAAC,CAAC;IAE5E,OAAO,OAAO,CACZ,WAAW,EACX,MAAM,EACN,UAAU,EACV,WAAW,EACX,kBAAkB,CAAC,eAAe,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,aAAa,EAAE,qBAAqB,CAAC,CAC9F,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Every public data shape in edfcore.
+ *
+ * Layer 0. Types only — this module emits no runtime code, so any layer may import it without
+ * creating a dependency edge.
+ *
+ * Two conventions run through the whole file:
+ *
+ * 1. A field that may be absent is declared `T | undefined` and is always present as a key.
+ *    Optional (`?`) is reserved for *options* the caller passes in. Reading a result should
+ *    never require knowing whether a key exists.
+ * 2. Anything that can be checked against the file is exposed twice — as parsed value and as
+ *    the raw bytes it came from. edfcore never destroys evidence.
+ */
+import type { EdfDiagnosticCode, EdfSeverity } from './diagnostics/codes.js';
+export type { EdfDiagnosticCode, EdfKnownDiagnosticCode, EdfSeverity, } from './diagnostics/codes.js';
+export interface AbortSignalLike {
+    readonly aborted: boolean;
+}
+export interface BlobLike {
+    readonly size: number;
+    slice(start?: number, end?: number): BlobLike;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface HttpResponseLike {
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * `globalThis.fetch` is assignable to this.
+ *
+ * `signal` is deliberately absent from `init`: naming it would drag in the real `AbortSignal`
+ * by parameter contravariance, which is the exact DOM dependency these shims exist to avoid.
+ * It is still passed at runtime.
+ */
+export type FetchLike = (url: string, init: {
+    headers: Record<string, string>;
+    method?: string;
+}) => Promise<HttpResponseLike>;
+export interface ReadOptions {
+    readonly signal?: AbortSignalLike;
+    /** Refuse before allocating rather than dying inside it. Default 256 MiB. */
+    readonly maxMaterializeBytes?: number;
+}
+export interface ParseOptions {
+    /**
+     * When true the first would-be diagnostic throws `EdfFormatError` carrying it, so every
+     * `diagnostics` array is consequently empty. Check order is pinned and tested, which is what
+     * makes error identity stable across refactors.
+     */
+    readonly strict?: boolean;
+}
+export type OpenOptions = ParseOptions & ReadOptions;
+/**
+ * A random-access byte range reader.
+ *
+ * CONTRACT, verified on every call including user-supplied sources: `read` resolves with
+ * EXACTLY `length` bytes or rejects. It never pads and never truncates. The returned array is
+ * owned by the caller, so a caching implementation must hand back a copy.
+ */
+export interface ByteSource {
+    readonly byteLength: number;
+    read(offset: number, length: number, options?: ReadOptions): Promise<Uint8Array>;
+    close?(): Promise<void> | void;
+}
+export interface HttpSourceOptions extends ReadOptions {
+    readonly fetch?: FetchLike;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly byteLength?: number;
+    readonly maxConcurrency?: number;
+    /** Server answered 200 instead of 206. Default false, i.e. throw rather than silently
+     *  buffering gigabytes the caller did not ask for. */
+    readonly allowFullDownload?: boolean;
+}
+export interface CacheOptions {
+    /** Block size in bytes. Default 1 MiB. Blocks are byte-aligned, not record-aligned: the
+     *  cache is format-independent by construction and never sees a header to learn a record
+     *  size from. Round this to a multiple of `header.recordByteLength` yourself if you want
+     *  block boundaries to fall on record boundaries. */
+    readonly blockBytes?: number;
+    /** LRU budget. Default 64 MiB. */
+    readonly maxBytes?: number;
+}
+export type EdfVariant = 'EDF' | 'EDF+C' | 'EDF+D' | 'BDF' | 'BDF+C' | 'BDF+D';
+export interface EdfCalendarDate {
+    readonly year: number;
+    /** 1-12. Not a JavaScript month index. */
+    readonly month: number;
+    readonly day: number;
+}
+export interface EdfClockTime {
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/**
+ * EDF records local time at the patient with no timezone, so edfcore never produces a `Date`:
+ * a `Date` silently applies the reader's zone, and is worst exactly at DST boundaries.
+ */
+export interface EdfStartTime {
+    /** From the `dd.mm.yy` header field, through the 1985-2084 rule. */
+    readonly headerDate: EdfCalendarDate | undefined;
+    /** From the EDF+ recording-identification `Startdate` subfield — the only unambiguous
+     *  four-digit year, and the only way past 2084. */
+    readonly recordingIdDate: EdfCalendarDate | undefined;
+    readonly resolvedDate: EdfCalendarDate | undefined;
+    readonly dateSource: 'headerField' | 'recordingIdField' | 'none';
+    readonly clock: EdfClockTime;
+    readonly secondsSinceMidnight: number;
+}
+export interface EdfPatientId {
+    readonly raw: string;
+    readonly conformant: boolean;
+    readonly code: string | undefined;
+    readonly sex: 'F' | 'M' | undefined;
+    readonly birthDate: EdfCalendarDate | undefined;
+    readonly name: string | undefined;
+    readonly extraSubfields: readonly string[];
+}
+export interface EdfRecordingId {
+    readonly raw: string;
+    readonly conformant: boolean;
+    readonly startDate: EdfCalendarDate | undefined;
+    readonly investigationCode: string | undefined;
+    readonly technicianCode: string | undefined;
+    readonly equipmentCode: string | undefined;
+    readonly extraSubfields: readonly string[];
+}
+/**
+ * `physical = bitValue * (offset + digital)`.
+ *
+ * This is EDFlib's exact expression, kept verbatim for float64 bit-parity with pyEDFlib.
+ * It is *not* the numerically better form, and it must not be "simplified" — see
+ * `src/decode/physical.ts`.
+ */
+export interface EdfScale {
+    readonly bitValue: number;
+    readonly offset: number;
+}
+/** Header text exactly as written, before trimming or interpretation. */
+export interface EdfRawSignalFields {
+    readonly label: string;
+    readonly transducerType: string;
+    readonly physicalDimension: string;
+    readonly physicalMinimum: string;
+    readonly physicalMaximum: string;
+    readonly digitalMinimum: string;
+    readonly digitalMaximum: string;
+    readonly prefiltering: string;
+    readonly samplesPerRecord: string;
+    readonly reserved: string;
+}
+export interface EdfRawHeaderFields {
+    readonly version: string;
+    readonly patientId: string;
+    readonly recordingId: string;
+    readonly startDate: string;
+    readonly startTime: string;
+    readonly headerByteLength: string;
+    readonly reserved: string;
+    readonly recordCount: string;
+    readonly recordDuration: string;
+    readonly signalCount: string;
+}
+export interface EdfSignal {
+    readonly index: number;
+    readonly kind: 'data' | 'annotations';
+    /** Trimmed. `raw.label` keeps the padding. */
+    readonly label: string;
+    readonly transducerType: string;
+    readonly prefiltering: string;
+    /** Trimmed. `raw.physicalDimension` keeps the padding and the exact bytes. */
+    readonly physicalDimension: string;
+    /** Normalised for comparison only: the several encodings of micro all become `u`. */
+    readonly unit: string;
+    readonly physicalMinimum: number;
+    /** MAY be less than the minimum: that is a negative amplifier gain, it is legal, and
+     *  edfcore never "fixes" it. */
+    readonly physicalMaximum: number;
+    readonly digitalMinimum: number;
+    readonly digitalMaximum: number;
+    /** Authoritative. Sample indexing uses this, never a rate. */
+    readonly samplesPerRecord: number;
+    /** Derived. `undefined` exactly when `recordDurationSeconds === 0`, which is legal.
+     *  Never index by this. */
+    readonly sampleRateHz: number | undefined;
+    readonly sampleCount: number;
+    /** `undefined` when scaling is impossible or unsafe: a degenerate or inverted digital
+     *  range, a degenerate physical range, or a log-transformed channel. `toPhysical` then
+     *  throws `EdfScalingError`; `decodeDigital` keeps working. */
+    readonly scale: EdfScale | undefined;
+    /** Byte offset of this signal's block within one data record. */
+    readonly recordByteOffset: number;
+    readonly recordByteLength: number;
+    readonly raw: EdfRawSignalFields;
+}
+export interface EdfHeader {
+    readonly variant: EdfVariant;
+    readonly continuity: 'continuous' | 'discontinuous';
+    readonly bytesPerSample: 2 | 3;
+    /** Always the computed `256 * (ns + 1)`, never the declared value. */
+    readonly headerByteLength: number;
+    /** What the file claims at offset 184. Kept so a mismatch stays visible. */
+    readonly declaredHeaderByteLength: number;
+    readonly recordByteLength: number;
+    readonly dataByteLength: number;
+    /** MAY legitimately be 0 — then never divide by it. */
+    readonly recordDurationSeconds: number;
+    readonly recordDurationTicks: bigint;
+    /** Resolved and non-negative. */
+    readonly recordCount: number;
+    /** Verbatim. `-1` means the writer never closed the file. */
+    readonly declaredRecordCount: number;
+    readonly recordCountSource: 'headerField' | 'sourceByteLength';
+    readonly startTime: EdfStartTime;
+    readonly patient: EdfPatientId;
+    readonly recording: EdfRecordingId;
+    readonly signals: readonly EdfSignal[];
+    readonly dataSignalIndices: readonly number[];
+    readonly annotationSignalIndices: readonly number[];
+    /** The full 44 reserved bytes, verbatim. */
+    readonly reserved: string;
+    readonly raw: EdfRawHeaderFields;
+    /** The whole header, for hexdumps and bug reports. */
+    readonly rawBytes: Uint8Array;
+    readonly diagnostics: readonly EdfDiagnostic[];
+}
+/** Start plus count, never start plus end: there is no inclusive/exclusive ambiguity. */
+export interface RecordRange {
+    readonly start: number;
+    readonly count: number;
+}
+export interface EdfSegment {
+    readonly index: number;
+    readonly records: RecordRange;
+    readonly startSeconds: number;
+    readonly startTicks: bigint;
+    readonly durationSeconds: number;
+    readonly endSeconds: number;
+}
+export interface EdfGap {
+    readonly beforeSegmentIndex: number;
+    readonly afterSegmentIndex: number;
+    readonly startSeconds: number;
+    readonly endSeconds: number;
+    readonly durationSeconds: number;
+}
+export interface EdfLocation {
+    readonly recordIndex: number;
+    readonly recordStartSeconds: number;
+    readonly offsetInRecordSeconds: number;
+}
+export interface EdfTimeline {
+    readonly recordCount: number;
+    readonly recordDurationSeconds: number;
+    /** Sub-second start carried by record 0's timekeeping TAL. In [0, 1). */
+    readonly startOffsetSeconds: number;
+    readonly startOffsetTicks: bigint;
+    /** Last record end minus first record start. Includes gaps. */
+    readonly spanSeconds: number;
+    /** Sum of record durations. Equals `spanSeconds` exactly when the file is contiguous. */
+    readonly coveredSeconds: number;
+    readonly diagnostics: readonly EdfDiagnostic[];
+}
+export interface EdfRecordIndex {
+    /** `probed` = record 0 and the last record only. `complete` = every record verified. */
+    readonly coverage: 'probed' | 'complete';
+    readonly recordCount: number;
+    /** Present only when `coverage === 'complete'`. Deliberately absent otherwise: no property
+     *  on this object may ever read as "continuous" when we have not checked. */
+    readonly segments: readonly EdfSegment[] | undefined;
+    readonly gaps: readonly EdfGap[] | undefined;
+    /** One targeted read of that record's annotation region. Memoised. */
+    onsetTicks(recordIndex: number, options?: ReadOptions): Promise<bigint>;
+    /** O(log recordCount) probes. Onsets are monotonic; any observed violation is fatal. */
+    locate(seconds: number, options?: ReadOptions): Promise<EdfLocation | undefined>;
+}
+export interface BuildIndexOptions extends ParseOptions, ReadOptions {
+    readonly onProgress?: (done: number, total: number) => void;
+}
+export interface EdfChunkSignal {
+    readonly signalIndex: number;
+    /** The truth. Never padded to a round number. */
+    readonly sampleCount: number;
+    readonly digital: Int32Array;
+    /** Index of the first sample on this signal's own sample grid. */
+    readonly firstSampleIndex: number;
+    /** Start of this signal's samples. A record-aligned read gives every signal the same
+     *  value, since they all begin at the same record; it becomes genuinely per-signal after
+     *  `trimToWindow`, where each signal's own sample grid decides the boundary. */
+    readonly startSeconds: number;
+    /** Counted during decode, so it costs nothing. A non-zero count means the declared
+     *  digital range is wrong, not that the samples are. */
+    readonly outOfDigitalRangeCount: number;
+}
+export interface EdfChunk {
+    readonly records: RecordRange;
+    readonly startSeconds: number;
+    readonly durationSeconds: number;
+    readonly byteOffset: number;
+    /** Bytes actually read from the source. Makes overread visible instead of invisible. */
+    readonly byteLength: number;
+    readonly signals: readonly EdfChunkSignal[];
+    readonly precededByGap: EdfGap | undefined;
+    readonly diagnostics: readonly EdfDiagnostic[];
+}
+export interface EdfAnnotation {
+    /** Verbatim on-disk value, relative to the header startdate/starttime (EDF+ 2.2.4). */
+    readonly onsetSecondsFromHeaderStart: number;
+    /** Rebased to the first record's true start — the EDFlib/pyEDFlib/MNE convention. */
+    readonly onsetSecondsFromFirstRecord: number;
+    /** Exact, in 100 ns units. Compare event times with this, never with the floats. */
+    readonly onsetTicks: bigint;
+    /** The original digits, so precision is never lost to a round-trip. */
+    readonly onsetRaw: string;
+    readonly durationSeconds: number | undefined;
+    readonly durationTicks: bigint | undefined;
+    readonly durationRaw: string | undefined;
+    /** Verbatim. Never trimmed, never case-folded. */
+    readonly text: string;
+    /** From the EDF+ `description@@channel` convention. */
+    readonly channelLabel: string | undefined;
+    readonly signalIndex: number;
+    readonly recordIndex: number;
+    readonly byteOffsetInRecord: number;
+    readonly textEncoding: 'utf-8' | 'latin-1-fallback';
+}
+export interface EdfAnnotationsResult {
+    /** Timekeeping TALs and empty texts excluded. Stable sort by
+     *  (onsetTicks, signalIndex, byteOffsetInRecord). */
+    readonly annotations: readonly EdfAnnotation[];
+    /** One entry per record in the decoded range. This is the primitive the timeline is
+     *  built from. */
+    readonly recordOnsetTicks: BigInt64Array;
+    readonly diagnostics: readonly EdfDiagnostic[];
+}
+export interface EdfDiagnostic {
+    readonly code: EdfDiagnosticCode;
+    readonly severity: EdfSeverity;
+    /** Names the field, the raw bytes as written, the rule, and an actionable next step. */
+    readonly message: string;
+    readonly field: string | undefined;
+    readonly byteOffset: number | undefined;
+    readonly byteLength: number | undefined;
+    readonly rawBytes: Uint8Array | undefined;
+    readonly raw: string | undefined;
+    readonly expected: string | undefined;
+    readonly actual: string | undefined;
+    readonly signalIndex: number | undefined;
+    readonly recordIndex: number | undefined;
+    /** A spec clause, e.g. 'EDF+ additional specification 5'. Verifiable and stable, unlike a
+     *  claim about how some other library behaves. */
+    readonly specReference: string | undefined;
+}
+export interface EdfRecording {
+    readonly source: ByteSource;
+    readonly header: EdfHeader;
+    readonly timeline: EdfTimeline;
+    readonly index: EdfRecordIndex;
+}
+export interface RecordSelection {
+    readonly records: RecordRange;
+    /** Required, with no "all signals" default: a 256-channel file must never be read
+     *  wholesale because an argument was omitted. */
+    readonly signalIndices: readonly number[];
+}
+export interface WindowSelection {
+    readonly startSeconds: number;
+    readonly durationSeconds: number;
+    readonly signalIndices: readonly number[];
+}
+export interface DecodeAnnotationsOptions extends ParseOptions {
+    /** Defaults to every annotation signal. Only the first carries timekeeping. */
+    readonly signalIndices?: readonly number[];
+}
+/** Header-only triage. Reads at most 128 KiB and never throws on malformed content. */
+export interface EdfInspection {
+    readonly ok: boolean;
+    readonly variant: EdfVariant | undefined;
+    readonly header: EdfHeader | undefined;
+    readonly byteLength: number;
+    readonly bytesRead: number;
+    readonly headerBytes: Uint8Array | undefined;
+    readonly diagnostics: readonly EdfDiagnostic[];
+}
+export interface ValidateOptions extends ReadOptions {
+    /** Reuse a completed index so conformance costs one traversal, not two. */
+    readonly index?: EdfRecordIndex;
+    readonly scanSamples?: boolean;
+    readonly onProgress?: (done: number, total: number) => void;
+}
+export interface ObservedSignalStats {
+    readonly signalIndex: number;
+    readonly observedDigitalMin: number;
+    readonly observedDigitalMax: number;
+    readonly outOfDigitalRangeCount: number;
+    readonly sampleCount: number;
+}
+export interface ValidationReport {
+    readonly ok: boolean;
+    readonly diagnostics: readonly EdfDiagnostic[];
+    readonly recordsScanned: number;
+    readonly bytesRead: number;
+    readonly signalStats: readonly ObservedSignalStats[];
+}
+//# sourceMappingURL=types.d.ts.map