edfcore 0.1.0

package/dist/time/segments.js

@@ -0,0 +1,87 @@
+/**
+ * Record onsets to segments and gaps.
+ *
+ * Layer 4. Pure and synchronous, and structural only: it reports the shape the onsets actually
+ * have and judges none of it. Monotonicity and the spacing rules belong to `time/timeline.ts`,
+ * which is their sole owner — run `assertMonotonicOnsetArray` on the same array first, and a gap
+ * can then only have a non-negative duration.
+ *
+ * Only `buildRecordIndex` calls this, because only a complete traversal has every onset. The
+ * boundary rule is the one edfcore states everywhere else: a new segment starts wherever
+ * `onset[r] !== onset[r - 1] + recordDurationTicks`, in exact ticks. Not "differs by more than an
+ * epsilon" — a float tolerance is how a one-sample overlap becomes invisible.
+ *
+ * Every second here is elapsed recording time, measured from record 0's start (see
+ * `time/timeline.ts`), so `segment.startTicks` is the rebased value and
+ * `ticksToSeconds(segment.startTicks) === segment.startSeconds` holds by construction.
+ */
+import { ticksToSeconds } from '../tal/ticks.js';
+const EMPTY_SEGMENTATION = Object.freeze({
+    segments: Object.freeze([]),
+    gaps: Object.freeze([]),
+});
+/**
+ * `onsetTicks` holds one entry per record, record 0 first — the `BigInt64Array` that
+ * `decodeAnnotations` returns for a full-file range fits directly.
+ *
+ * `originTicks` is the tick value that maps to `0` seconds. It defaults to `onsetTicks[0]`,
+ * which is record 0's own onset and therefore the recording's sub-second start offset.
+ */
+export function buildSegmentation(onsetTicks, recordDurationTicks, originTicks) {
+    const recordCount = onsetTicks.length;
+    if (recordCount === 0)
+        return EMPTY_SEGMENTATION;
+    const firstOnset = onsetTicks[0];
+    if (firstOnset === undefined)
+        return EMPTY_SEGMENTATION;
+    const origin = originTicks ?? firstOnset;
+    const segments = [];
+    const bounds = [];
+    let segmentStart = 0;
+    let segmentStartTicks = firstOnset;
+    const closeSegment = (endExclusive) => {
+        const count = endExclusive - segmentStart;
+        const startTicks = segmentStartTicks - origin;
+        const durationTicks = BigInt(count) * recordDurationTicks;
+        const endTicks = startTicks + durationTicks;
+        segments.push({
+            index: segments.length,
+            records: { start: segmentStart, count },
+            startSeconds: ticksToSeconds(startTicks),
+            startTicks,
+            durationSeconds: ticksToSeconds(durationTicks),
+            endSeconds: ticksToSeconds(endTicks),
+        });
+        bounds.push({ startTicks, endTicks });
+    };
+    for (let record = 1; record < recordCount; record += 1) {
+        const previous = onsetTicks[record - 1];
+        const current = onsetTicks[record];
+        // A missing entry cannot happen for a BigInt64Array of this length; skipping rather than
+        // asserting keeps a hand-built ArrayLike from turning a structural walk into a throw.
+        if (previous === undefined || current === undefined)
+            continue;
+        if (current === previous + recordDurationTicks)
+            continue;
+        closeSegment(record);
+        segmentStart = record;
+        segmentStartTicks = current;
+    }
+    closeSegment(recordCount);
+    const gaps = [];
+    for (let index = 1; index < bounds.length; index += 1) {
+        const before = bounds[index - 1];
+        const after = bounds[index];
+        if (before === undefined || after === undefined)
+            continue;
+        gaps.push({
+            beforeSegmentIndex: index - 1,
+            afterSegmentIndex: index,
+            startSeconds: ticksToSeconds(before.endTicks),
+            endSeconds: ticksToSeconds(after.startTicks),
+            durationSeconds: ticksToSeconds(after.startTicks - before.endTicks),
+        });
+    }
+    return { segments: Object.freeze(segments), gaps: Object.freeze(gaps) };
+}
+//# sourceMappingURL=segments.js.map

package/dist/time/segments.js.map

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

package/dist/time/timeline.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The recording's time axis, built from probed record onsets.
+ *
+ * Layer 4. Pure and synchronous: it is handed onsets that someone else read, and it decides what
+ * they mean. Sole owner of what makes a timeline valid — `tal/annotations.ts` produces
+ * `recordOnsetTicks` and deliberately passes no judgement on it, so monotonicity and
+ * record-onset spacing are enforced here and nowhere else.
+ *
+ * TIME AXIS, fixed here for the whole library: `t = 0` is the START OF RECORD 0, not the header
+ * start time. Record 0's timekeeping onset is `startOffsetTicks` — in [0, 1) s — and it is the
+ * bridge back to the header clock. Every other second edfcore reports (segment, gap, chunk,
+ * window bound) is elapsed recording time. This is the EDFlib/pyEDFlib/MNE convention, and it is
+ * the one under which sample `n` of a signal sits at exactly
+ * `n * recordDuration / samplesPerRecord` with no sub-second constant to remember.
+ */
+import type { EdfDiagnostic, EdfHeader, EdfTimeline, ParseOptions } from '../types.js';
+/** One record onset as observed on disk: which record, and its exact timekeeping value. */
+export interface RecordOnsetProbe {
+    readonly recordIndex: number;
+    /** Verbatim, relative to the header start time — the axis rebasing has not happened yet. */
+    readonly onsetTicks: bigint;
+}
+export interface TimelineInput {
+    readonly header: EdfHeader;
+    /**
+     * Ascending by `recordIndex`, first entry record 0 and last entry record `recordCount - 1`.
+     * In practice the two probes `buildTimeline` reads; a single-record file supplies one entry
+     * that is both. Empty exactly when the file has no records.
+     */
+    readonly probes: readonly RecordOnsetProbe[];
+    /**
+     * Diagnostics from decoding the probed records, folded into `timeline.diagnostics` so one
+     * array explains the whole timeline. A `START_OFFSET_OUT_OF_RANGE` already present here is not
+     * repeated below.
+     */
+    readonly probeDiagnostics?: readonly EdfDiagnostic[];
+}
+/**
+ * Fatal, at any observed pair: a later record starting earlier than an earlier one makes every
+ * time-based answer for the file wrong, so edfcore refuses to derive any of them.
+ *
+ * Equal onsets are not a violation — a file with `recordDuration = 0` has every record at the
+ * same instant legally, and an insufficient advance is spacing, which is a warning.
+ */
+export declare function assertMonotonicOnsets(earlier: RecordOnsetProbe, later: RecordOnsetProbe): void;
+/**
+ * `assertMonotonicOnsets` across a full onset array, which is what `buildRecordIndex` has.
+ *
+ * `firstRecordIndex` is the record `onsetTicks[0]` belongs to, so the diagnostic names the record
+ * in the file rather than a position in the array.
+ */
+export declare function assertMonotonicOnsetArray(onsetTicks: ArrayLike<bigint>, firstRecordIndex?: number): void;
+/**
+ * `EdfTimeline` from the probed onsets plus the header.
+ *
+ * `spanSeconds` and `coveredSeconds` are computed independently — last record end minus first
+ * record start, against the sum of the record durations — because their being equal is the
+ * statement "this file is contiguous as far as two reads can tell". Deriving either from the
+ * other would make that identity true by construction and worth nothing.
+ */
+export declare function buildTimelineFromProbes(input: TimelineInput, options?: ParseOptions): EdfTimeline;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/time/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/time/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIvF,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAkB9F;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,SAAS,CAAC,MAAM,CAAC,EAC7B,gBAAgB,GAAE,MAAU,GAC3B,IAAI,CAUN;AAiID;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CA4DjG"}

package/dist/time/timeline.js

@@ -0,0 +1,227 @@
+/**
+ * The recording's time axis, built from probed record onsets.
+ *
+ * Layer 4. Pure and synchronous: it is handed onsets that someone else read, and it decides what
+ * they mean. Sole owner of what makes a timeline valid — `tal/annotations.ts` produces
+ * `recordOnsetTicks` and deliberately passes no judgement on it, so monotonicity and
+ * record-onset spacing are enforced here and nowhere else.
+ *
+ * TIME AXIS, fixed here for the whole library: `t = 0` is the START OF RECORD 0, not the header
+ * start time. Record 0's timekeeping onset is `startOffsetTicks` — in [0, 1) s — and it is the
+ * bridge back to the header clock. Every other second edfcore reports (segment, gap, chunk,
+ * window bound) is elapsed recording time. This is the EDFlib/pyEDFlib/MNE convention, and it is
+ * the one under which sample `n` of a signal sits at exactly
+ * `n * recordDuration / samplesPerRecord` with no sub-second constant to remember.
+ */
+import { TICKS_PER_SECOND } from '../constants.js';
+import { DiagnosticSink, fatalError } from '../diagnostics/collector.js';
+import { ticksToSeconds } from '../tal/ticks.js';
+const TIMEKEEPING_SPEC = 'EDF+ specification 2.2.1 (time keeping of data records)';
+/**
+ * Fatal, at any observed pair: a later record starting earlier than an earlier one makes every
+ * time-based answer for the file wrong, so edfcore refuses to derive any of them.
+ *
+ * Equal onsets are not a violation — a file with `recordDuration = 0` has every record at the
+ * same instant legally, and an insufficient advance is spacing, which is a warning.
+ */
+export function assertMonotonicOnsets(earlier, later) {
+    if (later.onsetTicks >= earlier.onsetTicks)
+        return;
+    throw fatalError({
+        code: 'TIMELINE_NOT_MONOTONIC',
+        message: `record ${later.recordIndex} starts at ${ticksToSeconds(later.onsetTicks)} s, before ` +
+            `record ${earlier.recordIndex} at ${ticksToSeconds(earlier.onsetTicks)} s ` +
+            `(${later.onsetTicks} against ${earlier.onsetTicks} ticks of 100 ns). ` +
+            'Rule: record onsets never decrease, in EDF+C or EDF+D — the timekeeping TAL of record r ' +
+            "is that record's start relative to the header start time. " +
+            'Next: every time-based answer for this file would be wrong, so edfcore derives none of ' +
+            'them; read by record index with readRecords(), or repair the timekeeping TALs.',
+        field: 'timekeeping TAL',
+        expected: `onset >= ${earlier.onsetTicks} ticks`,
+        actual: `${later.onsetTicks} ticks`,
+        recordIndex: later.recordIndex,
+        specReference: TIMEKEEPING_SPEC,
+    });
+}
+/**
+ * `assertMonotonicOnsets` across a full onset array, which is what `buildRecordIndex` has.
+ *
+ * `firstRecordIndex` is the record `onsetTicks[0]` belongs to, so the diagnostic names the record
+ * in the file rather than a position in the array.
+ */
+export function assertMonotonicOnsetArray(onsetTicks, firstRecordIndex = 0) {
+    for (let position = 1; position < onsetTicks.length; position += 1) {
+        const previous = onsetTicks[position - 1];
+        const current = onsetTicks[position];
+        if (previous === undefined || current === undefined)
+            continue;
+        assertMonotonicOnsets({ recordIndex: firstRecordIndex + position - 1, onsetTicks: previous }, { recordIndex: firstRecordIndex + position, onsetTicks: current });
+    }
+}
+/**
+ * The probe array has to describe the whole file, because `spanSeconds` is defined by its two
+ * ends. A `RangeError` rather than an `EdfFormatError`: nothing here is the file's fault.
+ */
+function assertProbeShape(probes, recordCount) {
+    if (recordCount === 0) {
+        if (probes.length === 0)
+            return;
+        throw new RangeError(`buildTimelineFromProbes() received ${probes.length} onset probes for a file with no data ` +
+            'records. Next: pass an empty probes array when header.recordCount is 0.');
+    }
+    const first = probes[0];
+    const last = probes[probes.length - 1];
+    if (first === undefined || last === undefined) {
+        throw new RangeError(`buildTimelineFromProbes() received no onset probes for a file with ${recordCount} data ` +
+            'records, so neither the start offset nor the span is known. Next: probe record 0 and ' +
+            `record ${recordCount - 1} and pass both.`);
+    }
+    if (first.recordIndex !== 0 || last.recordIndex !== recordCount - 1) {
+        throw new RangeError(`buildTimelineFromProbes() received probes for records ${first.recordIndex}..` +
+            `${last.recordIndex}, but the start offset comes from record 0 and the span ends at ` +
+            `record ${recordCount - 1}. Next: probe both ends of the file; intermediate probes are ` +
+            'optional.');
+    }
+    for (let i = 1; i < probes.length; i += 1) {
+        const previous = probes[i - 1];
+        const probe = probes[i];
+        if (previous === undefined || probe === undefined)
+            continue;
+        if (probe.recordIndex <= previous.recordIndex) {
+            throw new RangeError(`buildTimelineFromProbes() received probes out of order: record ${probe.recordIndex} ` +
+                `follows record ${previous.recordIndex}. Next: sort the probes by record index.`);
+        }
+    }
+}
+function reportStartOffset(sink, startOffsetTicks) {
+    sink.report({
+        code: 'START_OFFSET_OUT_OF_RANGE',
+        message: `record 0 starts ${ticksToSeconds(startOffsetTicks)} s after the header start time ` +
+            `(${startOffsetTicks} ticks of 100 ns), but a sub-second start offset must be in [0, 1). ` +
+            "Rule: the onset of record 0's timekeeping TAL is the recording's sub-second start " +
+            'offset; the whole-second part of the start time lives in the header starttime field. ' +
+            'Next: the value was used as written, so the time axis still starts at record 0; compare ' +
+            'it with the header starttime, because a writer that encodes the start time twice ' +
+            'produces exactly this.',
+        field: 'timekeeping TAL',
+        expected: `0 <= onset < ${TICKS_PER_SECOND} ticks`,
+        actual: `${startOffsetTicks} ticks`,
+        recordIndex: 0,
+        specReference: TIMEKEEPING_SPEC,
+    });
+}
+/**
+ * The two-probe contiguity verdict.
+ *
+ * `onset[last] === onset[0] + (n - 1) * recordDuration`, in exact ticks, detects any NET drift of
+ * the timeline from two reads. It is not a proof of contiguity: a gap that a later overlap
+ * cancels exactly leaves the two ends where a contiguous file would put them, and only
+ * `buildRecordIndex()` or `validateRecording()` — which read every onset — can see that. The
+ * message says so, because a caller who believes this check is a proof will trust the wrong file.
+ */
+function reportDrift(sink, header, lastRecordIndex, observedTicks, expectedTicks) {
+    const driftTicks = observedTicks - expectedTicks;
+    const nominal = `record ${lastRecordIndex} starts at ${ticksToSeconds(observedTicks)} s where ` +
+        `startOffset + ${lastRecordIndex} * recordDuration is ${ticksToSeconds(expectedTicks)} s, ` +
+        `a net drift of ${ticksToSeconds(driftTicks)} s (${driftTicks} ticks of 100 ns)`;
+    const probeNote = 'Note: two probes detect any net drift of the timeline, but not a gap that an overlap ' +
+        'elsewhere cancels exactly — buildRecordIndex() reads every onset and does.';
+    if (header.continuity === 'continuous') {
+        sink.report({
+            code: 'DISCONTINUITY_IN_CONTINUOUS_FILE',
+            message: `the reserved field marks this file continuous, but ${nominal}. ` +
+                'Rule: in a continuous file every record onset is startOffset + recordIndex * ' +
+                'recordDuration; a recording with gaps is what EDF+D exists for. ' +
+                'Next: treat the file as discontinuous — buildRecordIndex() returns its segments and ' +
+                `gaps, and readWindow() then returns one chunk per contiguous run instead of ` +
+                'crossing a gap silently. ' +
+                probeNote,
+            field: 'timekeeping TAL',
+            expected: `${expectedTicks} ticks`,
+            actual: `${observedTicks} ticks`,
+            recordIndex: lastRecordIndex,
+            specReference: TIMEKEEPING_SPEC,
+        });
+        return;
+    }
+    // A discontinuous file is allowed to spread its records out; it is never allowed to pull them
+    // together, so only negative net drift is reportable here.
+    if (driftTicks >= 0n)
+        return;
+    sink.report({
+        code: 'RECORD_ONSET_SPACING_VIOLATION',
+        message: `${nominal}, so somewhere in this file a record starts before the previous one ends. ` +
+            'Rule: consecutive record onsets are spaced by at least the record duration — a ' +
+            'discontinuous file may leave gaps between records but never overlaps them. ' +
+            'Next: the onsets were used as written and nothing was reordered; buildRecordIndex() ' +
+            'reports which records overlap. ' +
+            probeNote,
+        field: 'timekeeping TAL',
+        expected: `>= ${expectedTicks} ticks`,
+        actual: `${observedTicks} ticks`,
+        recordIndex: lastRecordIndex,
+        specReference: TIMEKEEPING_SPEC,
+    });
+}
+/**
+ * `EdfTimeline` from the probed onsets plus the header.
+ *
+ * `spanSeconds` and `coveredSeconds` are computed independently — last record end minus first
+ * record start, against the sum of the record durations — because their being equal is the
+ * statement "this file is contiguous as far as two reads can tell". Deriving either from the
+ * other would make that identity true by construction and worth nothing.
+ */
+export function buildTimelineFromProbes(input, options) {
+    const header = input.header;
+    const recordCount = header.recordCount;
+    const durationTicks = header.recordDurationTicks;
+    assertProbeShape(input.probes, recordCount);
+    // Fatal, and checked before anything is derived: a non-monotonic timeline has no valid span,
+    // no valid offset, and no valid answer to any question a caller could ask of this object.
+    for (let i = 1; i < input.probes.length; i += 1) {
+        const previous = input.probes[i - 1];
+        const probe = input.probes[i];
+        if (previous === undefined || probe === undefined)
+            continue;
+        assertMonotonicOnsets(previous, probe);
+    }
+    const sink = new DiagnosticSink(options);
+    const priorDiagnostics = input.probeDiagnostics ?? [];
+    const first = input.probes[0];
+    const last = input.probes[input.probes.length - 1];
+    if (recordCount === 0 || first === undefined || last === undefined) {
+        return {
+            recordCount: 0,
+            recordDurationSeconds: header.recordDurationSeconds,
+            startOffsetSeconds: 0,
+            startOffsetTicks: 0n,
+            spanSeconds: 0,
+            coveredSeconds: 0,
+            diagnostics: Object.freeze(priorDiagnostics.slice()),
+        };
+    }
+    const startOffsetTicks = first.onsetTicks;
+    const spanTicks = last.onsetTicks + durationTicks - first.onsetTicks;
+    const coveredTicks = BigInt(recordCount) * durationTicks;
+    const expectedLastTicks = first.onsetTicks + BigInt(recordCount - 1) * durationTicks;
+    // decodeAnnotations already reports this for a range that began at record 0, which is exactly
+    // how record 0 is probed. Repeating it would double every strict-mode failure and every
+    // diagnostic count a test asserts.
+    const offsetAlreadyReported = priorDiagnostics.some((diagnostic) => diagnostic.code === 'START_OFFSET_OUT_OF_RANGE');
+    if (!offsetAlreadyReported && (startOffsetTicks < 0n || startOffsetTicks >= TICKS_PER_SECOND)) {
+        reportStartOffset(sink, startOffsetTicks);
+    }
+    if (last.onsetTicks !== expectedLastTicks) {
+        reportDrift(sink, header, last.recordIndex, last.onsetTicks, expectedLastTicks);
+    }
+    return {
+        recordCount,
+        recordDurationSeconds: header.recordDurationSeconds,
+        startOffsetSeconds: ticksToSeconds(startOffsetTicks),
+        startOffsetTicks,
+        spanSeconds: ticksToSeconds(spanTicks),
+        coveredSeconds: ticksToSeconds(coveredTicks),
+        diagnostics: Object.freeze([...priorDiagnostics, ...sink.diagnostics]),
+    };
+}
+//# sourceMappingURL=timeline.js.map

package/dist/time/timeline.js.map

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

package/dist/time/window.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 type { EdfChunkSignal, EdfHeader, EdfRecordIndex, EdfTimeline, RecordRange } from '../types.js';
+/**
+ * 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 declare function resolveTimeWindow(timeline: EdfTimeline, index: EdfRecordIndex, startSeconds: number, durationSeconds: number): readonly RecordRange[];
+/**
+ * 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 declare function trimToWindow(header: EdfHeader, chunkSignal: EdfChunkSignal, startSeconds: number, durationSeconds: number): EdfChunkSignal;
+//# sourceMappingURL=window.d.ts.map

package/dist/time/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../../src/time/window.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EACV,cAAc,EACd,SAAS,EACT,cAAc,EAEd,WAAW,EACX,WAAW,EACZ,MAAM,aAAa,CAAC;AAgDrB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB,SAAS,WAAW,EAAE,CAuExB;AAgED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,cAAc,EAC3B,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GACtB,cAAc,CAiDhB"}