edfcore 0.1.0

package/dist/bytes/view.js

@@ -0,0 +1,53 @@
+/**
+ * Bounds-checked slicing.
+ *
+ * Layer 0. Every offset here is a plain JS number — exact to 2^53 — and is never touched by
+ * `|0`, `<<`, `>>` or `>>>`. A data offset in a multi-gigabyte BDF routinely exceeds 2^31,
+ * where every bitwise operator silently wraps it to a negative number. (Bitwise ops are
+ * correct and required for SAMPLE decoding, which operates on 16- and 24-bit values.)
+ */
+import { decodeHeaderLatin1 } from './latin1.js';
+/**
+ * A plain `RangeError`, deliberately not `EdfRangeError`: reaching here means edfcore
+ * computed an offset wrongly, or a caller mixed a header with bytes from another file.
+ * `EdfRangeError` is reserved for the honest case of a caller asking for records that do not
+ * exist, and conflating the two would let an internal bug present itself as user error.
+ */
+function assertInBounds(bytes, offset, length) {
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+        throw new RangeError(`byte offset must be a non-negative safe integer, got ${offset}`);
+    }
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new RangeError(`byte length must be a non-negative safe integer, got ${length}`);
+    }
+    if (offset + length > bytes.length) {
+        throw new RangeError(`byte range [${offset}, ${offset + length}) is outside the ${bytes.length}-byte buffer`);
+    }
+}
+/**
+ * A VIEW of `length` bytes at `offset`, sharing memory with `bytes` — no copy is made.
+ *
+ * Nothing in edfcore mutates a source buffer, so a view is safe to read for as long as the
+ * buffer lives. A caller that pools or reuses buffers must not retain the view past that
+ * reuse: use `copyBytes` when the bytes have to outlive the read that produced them.
+ */
+export function sliceBytes(bytes, offset, length) {
+    assertInBounds(bytes, offset, length);
+    return bytes.subarray(offset, offset + length);
+}
+/** `length` bytes at `offset`, copied into a buffer of their own. */
+export function copyBytes(bytes, offset, length) {
+    assertInBounds(bytes, offset, length);
+    return bytes.slice(offset, offset + length);
+}
+/**
+ * The RAW, untrimmed text of a fixed-width header field, decoded as ISO-8859-1.
+ *
+ * Untrimmed on purpose: `raw.*` on the header exposes what the file actually wrote, and the
+ * numeric grammars need the padding to tell a right-justified field from a conformant one.
+ * Callers that want the value trim it themselves with `trimEdfField`.
+ */
+export function readAsciiField(bytes, offset, length) {
+    return decodeHeaderLatin1(sliceBytes(bytes, offset, length));
+}
+//# sourceMappingURL=view.js.map

package/dist/bytes/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/bytes/view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;GAKG;AACH,SAAS,cAAc,CAAC,KAAiB,EAAE,MAAc,EAAE,MAAc;IACvE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,UAAU,CAAC,wDAAwD,MAAM,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,UAAU,CAAC,wDAAwD,MAAM,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAClB,eAAe,MAAM,KAAK,MAAM,GAAG,MAAM,oBAAoB,KAAK,CAAC,MAAM,cAAc,CACxF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAc,EAAE,MAAc;IAC1E,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AACjD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,SAAS,CAAC,KAAiB,EAAE,MAAc,EAAE,MAAc;IACzE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAiB,EAAE,MAAc,EAAE,MAAc;IAC9E,OAAO,kBAAkB,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Format constants.
+ *
+ * Layer 0. Imports nothing. Every magic number the parser relies on lives here with the
+ * clause it comes from, so no other file needs a bare literal.
+ */
+/** The fixed header is one of these, and each signal adds exactly one more. */
+export declare const EDF_HEADER_BLOCK_BYTES: 256;
+/** Total header size is always `EDF_HEADER_BLOCK_BYTES * (signalCount + 1)`. */
+export declare const EDF_SIGNAL_HEADER_BYTES: 256;
+/** Trimmed, case-sensitive. On disk the field is `'EDF Annotations '` — 15 chars plus a pad. */
+export declare const EDF_ANNOTATIONS_LABEL: "EDF Annotations";
+export declare const BDF_ANNOTATIONS_LABEL: "BDF Annotations";
+/** EDF spec recommendation, not a limit. Exceeding it is a warning, never an error. */
+export declare const EDF_RECOMMENDED_MAX_RECORD_BYTES: 61440;
+/**
+ * Time is compared in exact 100 ns ticks, never in floats. Float equality on event times is
+ * how ERP alignment silently breaks.
+ */
+export declare const TICKS_PER_SECOND = 10000000n;
+/** 16-bit two's complement. */
+export declare const EDF_DIGITAL_MIN: -32768;
+export declare const EDF_DIGITAL_MAX: 32767;
+/** 24-bit two's complement, sign-extended from bit 23. */
+export declare const BDF_DIGITAL_MIN: -8388608;
+export declare const BDF_DIGITAL_MAX: 8388607;
+/** ns lives in a 4-byte field, so it cannot exceed four digits. */
+export declare const EDF_MAX_SIGNAL_COUNT: 9999;
+/** Default ceiling for any read that allocates. Refused before allocating, not during. */
+export declare const DEFAULT_MAX_MATERIALIZE_BYTES: number;
+/** TAL structural bytes. Every byte of a multi-byte UTF-8 sequence is >= 0x80, so these can
+ *  never collide with text — which is why splitting on structure before decoding is safe. */
+export declare const TAL_ONSET_DURATION_SEPARATOR: 21;
+export declare const TAL_FIELD_TERMINATOR: 20;
+export declare const TAL_TERMINATOR: 0;
+/** Fixed-header field offsets and lengths, per the EDF specification. */
+export declare const HEADER_FIELDS: {
+    readonly version: {
+        readonly offset: 0;
+        readonly length: 8;
+    };
+    readonly patientId: {
+        readonly offset: 8;
+        readonly length: 80;
+    };
+    readonly recordingId: {
+        readonly offset: 88;
+        readonly length: 80;
+    };
+    readonly startDate: {
+        readonly offset: 168;
+        readonly length: 8;
+    };
+    readonly startTime: {
+        readonly offset: 176;
+        readonly length: 8;
+    };
+    readonly headerByteLength: {
+        readonly offset: 184;
+        readonly length: 8;
+    };
+    readonly reserved: {
+        readonly offset: 192;
+        readonly length: 44;
+    };
+    readonly recordCount: {
+        readonly offset: 236;
+        readonly length: 8;
+    };
+    readonly recordDuration: {
+        readonly offset: 244;
+        readonly length: 8;
+    };
+    readonly signalCount: {
+        readonly offset: 252;
+        readonly length: 4;
+    };
+};
+/**
+ * Per-signal header field widths, in the order they appear.
+ *
+ * The layout is FIELD-MAJOR, not one struct per signal: all `ns` labels, then all `ns`
+ * transducers, and so on. For signal `i`, a field's address is
+ * `256 + ns * (sum of widths before it) + i * (its own width)`.
+ */
+export declare const SIGNAL_FIELD_WIDTHS: {
+    readonly label: 16;
+    readonly transducerType: 80;
+    readonly physicalDimension: 8;
+    readonly physicalMinimum: 8;
+    readonly physicalMaximum: 8;
+    readonly digitalMinimum: 8;
+    readonly digitalMaximum: 8;
+    readonly prefiltering: 80;
+    readonly samplesPerRecord: 8;
+    readonly reserved: 32;
+};
+/** Cumulative width preceding each per-signal field. Multiply by ns to get its block start. */
+export declare const SIGNAL_FIELD_BLOCK_OFFSETS: {
+    readonly label: 0;
+    readonly transducerType: 16;
+    readonly physicalDimension: 96;
+    readonly physicalMinimum: 104;
+    readonly physicalMaximum: 112;
+    readonly digitalMinimum: 120;
+    readonly digitalMaximum: 128;
+    readonly prefiltering: 136;
+    readonly samplesPerRecord: 216;
+    readonly reserved: 224;
+};
+/** Published package version. Kept in sync with package.json by a test. */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,EAAG,GAAY,CAAC;AAEnD,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,EAAG,GAAY,CAAC;AAEpD,gGAAgG;AAChG,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAChE,eAAO,MAAM,qBAAqB,EAAG,iBAA0B,CAAC;AAEhE,uFAAuF;AACvF,eAAO,MAAM,gCAAgC,EAAG,KAAc,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,+BAA+B;AAC/B,eAAO,MAAM,eAAe,EAAG,CAAC,KAAc,CAAC;AAC/C,eAAO,MAAM,eAAe,EAAG,KAAc,CAAC;AAE9C,0DAA0D;AAC1D,eAAO,MAAM,eAAe,EAAG,CAAC,OAAgB,CAAC;AACjD,eAAO,MAAM,eAAe,EAAG,OAAgB,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,EAAG,IAAa,CAAC;AAElD,0FAA0F;AAC1F,eAAO,MAAM,6BAA6B,EAAE,MAA0B,CAAC;AAEvE;6FAC6F;AAC7F,eAAO,MAAM,4BAA4B,EAAG,EAAa,CAAC;AAC1D,eAAO,MAAM,oBAAoB,EAAG,EAAa,CAAC;AAClD,eAAO,MAAM,cAAc,EAAG,CAAa,CAAC;AAE5C,yEAAyE;AACzE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAWhB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;CAWtB,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,0BAA0B;;;;;;;;;;;CAW7B,CAAC;AAEX,2EAA2E;AAC3E,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/constants.js

@@ -0,0 +1,83 @@
+/**
+ * Format constants.
+ *
+ * Layer 0. Imports nothing. Every magic number the parser relies on lives here with the
+ * clause it comes from, so no other file needs a bare literal.
+ */
+/** The fixed header is one of these, and each signal adds exactly one more. */
+export const EDF_HEADER_BLOCK_BYTES = 256;
+/** Total header size is always `EDF_HEADER_BLOCK_BYTES * (signalCount + 1)`. */
+export const EDF_SIGNAL_HEADER_BYTES = 256;
+/** Trimmed, case-sensitive. On disk the field is `'EDF Annotations '` — 15 chars plus a pad. */
+export const EDF_ANNOTATIONS_LABEL = 'EDF Annotations';
+export const BDF_ANNOTATIONS_LABEL = 'BDF Annotations';
+/** EDF spec recommendation, not a limit. Exceeding it is a warning, never an error. */
+export const EDF_RECOMMENDED_MAX_RECORD_BYTES = 61440;
+/**
+ * Time is compared in exact 100 ns ticks, never in floats. Float equality on event times is
+ * how ERP alignment silently breaks.
+ */
+export const TICKS_PER_SECOND = 10000000n;
+/** 16-bit two's complement. */
+export const EDF_DIGITAL_MIN = -32768;
+export const EDF_DIGITAL_MAX = 32767;
+/** 24-bit two's complement, sign-extended from bit 23. */
+export const BDF_DIGITAL_MIN = -8388608;
+export const BDF_DIGITAL_MAX = 8388607;
+/** ns lives in a 4-byte field, so it cannot exceed four digits. */
+export const EDF_MAX_SIGNAL_COUNT = 9999;
+/** Default ceiling for any read that allocates. Refused before allocating, not during. */
+export const DEFAULT_MAX_MATERIALIZE_BYTES = 256 * 1024 * 1024;
+/** TAL structural bytes. Every byte of a multi-byte UTF-8 sequence is >= 0x80, so these can
+ *  never collide with text — which is why splitting on structure before decoding is safe. */
+export const TAL_ONSET_DURATION_SEPARATOR = 0x15;
+export const TAL_FIELD_TERMINATOR = 0x14;
+export const TAL_TERMINATOR = 0x00;
+/** Fixed-header field offsets and lengths, per the EDF specification. */
+export const HEADER_FIELDS = {
+    version: { offset: 0, length: 8 },
+    patientId: { offset: 8, length: 80 },
+    recordingId: { offset: 88, length: 80 },
+    startDate: { offset: 168, length: 8 },
+    startTime: { offset: 176, length: 8 },
+    headerByteLength: { offset: 184, length: 8 },
+    reserved: { offset: 192, length: 44 },
+    recordCount: { offset: 236, length: 8 },
+    recordDuration: { offset: 244, length: 8 },
+    signalCount: { offset: 252, length: 4 },
+};
+/**
+ * Per-signal header field widths, in the order they appear.
+ *
+ * The layout is FIELD-MAJOR, not one struct per signal: all `ns` labels, then all `ns`
+ * transducers, and so on. For signal `i`, a field's address is
+ * `256 + ns * (sum of widths before it) + i * (its own width)`.
+ */
+export const SIGNAL_FIELD_WIDTHS = {
+    label: 16,
+    transducerType: 80,
+    physicalDimension: 8,
+    physicalMinimum: 8,
+    physicalMaximum: 8,
+    digitalMinimum: 8,
+    digitalMaximum: 8,
+    prefiltering: 80,
+    samplesPerRecord: 8,
+    reserved: 32,
+};
+/** Cumulative width preceding each per-signal field. Multiply by ns to get its block start. */
+export const SIGNAL_FIELD_BLOCK_OFFSETS = {
+    label: 0,
+    transducerType: 16,
+    physicalDimension: 96,
+    physicalMinimum: 104,
+    physicalMaximum: 112,
+    digitalMinimum: 120,
+    digitalMaximum: 128,
+    prefiltering: 136,
+    samplesPerRecord: 216,
+    reserved: 224,
+};
+/** Published package version. Kept in sync with package.json by a test. */
+export const VERSION = '0.1.0';
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

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

package/dist/decode/digital.d.ts

@@ -0,0 +1,49 @@
+/**
+ * De-interleaving and sign extension.
+ *
+ * Layer 3. Sole owner of turning record bytes into sample values: the 2- and 3-byte two's
+ * complement expressions exist here and nowhere else in edfcore.
+ *
+ * Bitwise operators appear in this file and are correct here — a sample is 16 or 24 bits, so
+ * `|` and `<<` are exact on it. They are never applied to an OFFSET: a data offset in a
+ * multi-gigabyte BDF routinely exceeds 2^31, where every bitwise operator silently wraps it
+ * negative. Every offset below is plain arithmetic, exact to 2^53.
+ */
+import type { EdfHeader, RecordRange } from '../types.js';
+/**
+ * The allocation ceiling for a decode that has to allocate.
+ *
+ * A trailing optional argument on functions whose signature is otherwise fixed by the public
+ * API, so passing nothing keeps the documented call shape and the 256 MiB default.
+ */
+export interface MaterializeOptions {
+    readonly maxMaterializeBytes?: number;
+}
+export interface DecodedDigital {
+    readonly digital: Int32Array;
+    /**
+     * Samples outside the DECLARED digital range, counted in the same pass that decodes them so
+     * `EdfChunkSignal.outOfDigitalRangeCount` costs nothing. edfcore never clamps: a non-zero
+     * count means the declared range is wrong, not that the samples are.
+     */
+    readonly outOfDigitalRangeCount: number;
+}
+/**
+ * Decode one signal out of a record range, with the out-of-declared-range tally.
+ *
+ * The count compares against `min`/`max` of the DECLARED digital minimum and maximum rather
+ * than against the pair as written: an inverted declaration (`digitalMinimum > digitalMaximum`)
+ * would otherwise report every sample in the file as out of range, which tells the caller
+ * nothing about the samples.
+ */
+export declare function decodeDigitalCounted(header: EdfHeader, recordBytes: Uint8Array, records: RecordRange, signalIndex: number, out?: Int32Array, options?: MaterializeOptions): DecodedDigital;
+/**
+ * `recordBytes` must be exactly `records.count * header.recordByteLength` bytes and must begin
+ * at record `records.start`; anything else throws `EdfRangeError`. `out` is reused when
+ * supplied and long enough.
+ *
+ * The out-of-range tally reaches callers through `EdfChunkSignal.outOfDigitalRangeCount` — it is the same single
+ * pass, so a caller never needs a second one to produce it.
+ */
+export declare function decodeDigital(header: EdfHeader, recordBytes: Uint8Array, records: RecordRange, signalIndex: number, out?: Int32Array, options?: MaterializeOptions): Int32Array;
+//# sourceMappingURL=digital.d.ts.map

package/dist/decode/digital.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digital.d.ts","sourceRoot":"","sources":["../../src/decode/digital.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAa,WAAW,EAAE,MAAM,aAAa,CAAC;AAIrE;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACzC;AAiKD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,cAAc,CA0BhB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,MAAM,EACnB,GAAG,CAAC,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,UAAU,CAEZ"}

package/dist/decode/digital.js

@@ -0,0 +1,180 @@
+/**
+ * De-interleaving and sign extension.
+ *
+ * Layer 3. Sole owner of turning record bytes into sample values: the 2- and 3-byte two's
+ * complement expressions exist here and nowhere else in edfcore.
+ *
+ * Bitwise operators appear in this file and are correct here — a sample is 16 or 24 bits, so
+ * `|` and `<<` are exact on it. They are never applied to an OFFSET: a data offset in a
+ * multi-gigabyte BDF routinely exceeds 2^31, where every bitwise operator silently wraps it
+ * negative. Every offset below is plain arithmetic, exact to 2^53.
+ */
+import { DEFAULT_MAX_MATERIALIZE_BYTES } from '../constants.js';
+import { EdfBudgetError, EdfChannelNotFoundError, EdfRangeError } from '../errors.js';
+const BYTES_PER_INT32 = 4;
+function assertWithinBudget(requiredBytes, what, options) {
+    const budgetBytes = options?.maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES;
+    if (requiredBytes <= budgetBytes)
+        return;
+    throw new EdfBudgetError(`Decoding ${what} needs a ${requiredBytes}-byte array, above the ${budgetBytes}-byte ` +
+        'maxMaterializeBytes budget, so the allocation was refused before it was attempted. ' +
+        'Next: decode fewer records per call, reuse an `out` array, or raise ' +
+        'options.maxMaterializeBytes.', { requiredBytes, budgetBytes });
+}
+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. Next: pass an index taken from header.signals, or resolve one with ' +
+        'getSignal(header, label).', { selector: signalIndex, availableLabels: header.signals.map((s) => s.label) });
+}
+/**
+ * `recordBytes` must be exactly the requested records and nothing else.
+ *
+ * Both halves matter. The range check catches a caller asking for records the file does not
+ * have; the length check catches a buffer that does not start where `records.start` says it
+ * does — which is unrecoverable rather than merely wrong, because nothing in the bytes
+ * identifies which record they came from.
+ */
+function assertRecordRange(header, recordBytes, records) {
+    const available = { start: 0, count: header.recordCount };
+    const startValid = Number.isSafeInteger(records.start) && records.start >= 0;
+    const countValid = Number.isSafeInteger(records.count) && records.count >= 0;
+    if (!startValid || !countValid || records.start + records.count > header.recordCount) {
+        throw new EdfRangeError(`records { start: ${records.start}, count: ${records.count} } is not inside the ` +
+            `${header.recordCount} data records this file contains. Next: clamp the range against ` +
+            'header.recordCount before decoding.', { requested: records, available });
+    }
+    const expectedBytes = records.count * header.recordByteLength;
+    if (recordBytes.length === expectedBytes)
+        return;
+    const wholeRecords = header.recordByteLength > 0 ? Math.floor(recordBytes.length / header.recordByteLength) : 0;
+    throw new EdfRangeError(`recordBytes is ${recordBytes.length} bytes, but ${records.count} records of ` +
+        `${header.recordByteLength} bytes each are exactly ${expectedBytes}. decodeDigital ` +
+        'cannot tell which record a differently sized buffer begins at, so it will not guess. ' +
+        'Next: pass the buffer returned by readRecordBytes(source, header, records) unmodified.', { requested: records, available: { start: records.start, count: wholeRecords } });
+}
+/**
+ * A plain `RangeError`, deliberately not `EdfRangeError`: a signal block that overflows its own
+ * record means the header's offset arithmetic is inconsistent with its record size, which is an
+ * edfcore bug or a hand-built header — never the caller asking for something reasonable.
+ */
+function assertSignalFitsRecord(header, signal, blockBytes) {
+    if (signal.recordByteOffset + blockBytes <= header.recordByteLength)
+        return;
+    throw new RangeError(`signal ${signal.index} occupies bytes [${signal.recordByteOffset}, ` +
+        `${signal.recordByteOffset + blockBytes}) of a ${header.recordByteLength}-byte record, ` +
+        'which does not fit. The header this was called with is internally inconsistent.');
+}
+/**
+ * The destination for `sampleCount` samples: `out` when it is large enough, otherwise a fresh
+ * array checked against the budget first.
+ *
+ * A longer `out` is narrowed with `subarray`, which shares its memory — the zero-allocation
+ * path survives — while keeping `result.length` equal to the true sample count, so no caller
+ * can mistake spare capacity for data.
+ */
+function resolveOut(out, sampleCount, options) {
+    if (out === undefined) {
+        assertWithinBudget(sampleCount * BYTES_PER_INT32, `${sampleCount} digital samples`, options);
+        return new Int32Array(sampleCount);
+    }
+    if (out.length < sampleCount) {
+        throw new RangeError(`out holds ${out.length} samples but this decode produces ${sampleCount}. Next: size the ` +
+            'reused array to records.count * signal.samplesPerRecord, or omit it and let ' +
+            'decodeDigital allocate.');
+    }
+    return out.length === sampleCount ? out : out.subarray(0, sampleCount);
+}
+/** EDF: little-endian 16-bit two's complement. Returns the out-of-declared-range count. */
+function decodeInt16(bytes, out, plan) {
+    const { recordCount, recordByteLength, recordByteOffset, samplesPerRecord } = plan;
+    const low = plan.digitalLow;
+    const high = plan.digitalHigh;
+    let outOfRange = 0;
+    let write = 0;
+    for (let r = 0; r < recordCount; r++) {
+        const base = r * recordByteLength + recordByteOffset;
+        for (let k = 0; k < samplesPerRecord; k++) {
+            const p = base + k * 2;
+            // In bounds by construction: assertRecordRange pinned bytes.length to
+            // recordCount * recordByteLength, and assertSignalFitsRecord pinned this block inside a
+            // record. A per-sample undefined check would cost more than the decode itself.
+            // biome-ignore lint/style/noNonNullAssertion: bounds are established above.
+            let value = bytes[p] | (bytes[p + 1] << 8);
+            if (value & 0x8000)
+                value -= 0x10000;
+            if (value < low || value > high)
+                outOfRange++;
+            out[write] = value;
+            write++;
+        }
+    }
+    return outOfRange;
+}
+/** BDF: little-endian 24-bit two's complement, sign-extended from bit 23. */
+function decodeInt24(bytes, out, plan) {
+    const { recordCount, recordByteLength, recordByteOffset, samplesPerRecord } = plan;
+    const low = plan.digitalLow;
+    const high = plan.digitalHigh;
+    let outOfRange = 0;
+    let write = 0;
+    for (let r = 0; r < recordCount; r++) {
+        const base = r * recordByteLength + recordByteOffset;
+        for (let k = 0; k < samplesPerRecord; k++) {
+            const p = base + k * 3;
+            // biome-ignore lint/style/noNonNullAssertion: see decodeInt16.
+            let value = bytes[p] | (bytes[p + 1] << 8) | (bytes[p + 2] << 16);
+            if (value & 0x800000)
+                value -= 0x1000000;
+            if (value < low || value > high)
+                outOfRange++;
+            out[write] = value;
+            write++;
+        }
+    }
+    return outOfRange;
+}
+/**
+ * Decode one signal out of a record range, with the out-of-declared-range tally.
+ *
+ * The count compares against `min`/`max` of the DECLARED digital minimum and maximum rather
+ * than against the pair as written: an inverted declaration (`digitalMinimum > digitalMaximum`)
+ * would otherwise report every sample in the file as out of range, which tells the caller
+ * nothing about the samples.
+ */
+export function decodeDigitalCounted(header, recordBytes, records, signalIndex, out, options) {
+    const signal = signalAt(header, signalIndex);
+    assertRecordRange(header, recordBytes, records);
+    const bytesPerSample = header.bytesPerSample;
+    const samplesPerRecord = signal.samplesPerRecord;
+    assertSignalFitsRecord(header, signal, samplesPerRecord * bytesPerSample);
+    const sampleCount = records.count * samplesPerRecord;
+    const digital = resolveOut(out, sampleCount, options);
+    const plan = {
+        recordCount: records.count,
+        recordByteLength: header.recordByteLength,
+        // `records.start` located the bytes; inside the buffer record 0 is at offset 0.
+        recordByteOffset: signal.recordByteOffset,
+        samplesPerRecord,
+        digitalLow: Math.min(signal.digitalMinimum, signal.digitalMaximum),
+        digitalHigh: Math.max(signal.digitalMinimum, signal.digitalMaximum),
+    };
+    const outOfDigitalRangeCount = bytesPerSample === 2
+        ? decodeInt16(recordBytes, digital, plan)
+        : decodeInt24(recordBytes, digital, plan);
+    return { digital, outOfDigitalRangeCount };
+}
+/**
+ * `recordBytes` must be exactly `records.count * header.recordByteLength` bytes and must begin
+ * at record `records.start`; anything else throws `EdfRangeError`. `out` is reused when
+ * supplied and long enough.
+ *
+ * The out-of-range tally reaches callers through `EdfChunkSignal.outOfDigitalRangeCount` — it is the same single
+ * pass, so a caller never needs a second one to produce it.
+ */
+export function decodeDigital(header, recordBytes, records, signalIndex, out, options) {
+    return decodeDigitalCounted(header, recordBytes, records, signalIndex, out, options).digital;
+}
+//# sourceMappingURL=digital.js.map

package/dist/decode/digital.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digital.js","sourceRoot":"","sources":["../../src/decode/digital.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGtF,MAAM,eAAe,GAAG,CAAC,CAAC;AAgC1B,SAAS,kBAAkB,CACzB,aAAqB,EACrB,IAAY,EACZ,OAAuC;IAEvC,MAAM,WAAW,GAAG,OAAO,EAAE,mBAAmB,IAAI,6BAA6B,CAAC;IAClF,IAAI,aAAa,IAAI,WAAW;QAAE,OAAO;IACzC,MAAM,IAAI,cAAc,CACtB,YAAY,IAAI,YAAY,aAAa,0BAA0B,WAAW,QAAQ;QACpF,qFAAqF;QACrF,sEAAsE;QACtE,8BAA8B,EAChC,EAAE,aAAa,EAAE,WAAW,EAAE,CAC/B,CAAC;AACJ,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,6EAA6E;QAC7E,2BAA2B,EAC7B,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;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,MAAiB,EAAE,WAAuB,EAAE,OAAoB;IACzF,MAAM,SAAS,GAAgB,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC;IACvE,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IAC7E,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACrF,MAAM,IAAI,aAAa,CACrB,oBAAoB,OAAO,CAAC,KAAK,YAAY,OAAO,CAAC,KAAK,uBAAuB;YAC/E,GAAG,MAAM,CAAC,WAAW,kEAAkE;YACvF,qCAAqC,EACvC,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAClC,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAC9D,IAAI,WAAW,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO;IACjD,MAAM,YAAY,GAChB,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,MAAM,IAAI,aAAa,CACrB,kBAAkB,WAAW,CAAC,MAAM,eAAe,OAAO,CAAC,KAAK,cAAc;QAC5E,GAAG,MAAM,CAAC,gBAAgB,2BAA2B,aAAa,kBAAkB;QACpF,uFAAuF;QACvF,wFAAwF,EAC1F,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CACjF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,sBAAsB,CAAC,MAAiB,EAAE,MAAiB,EAAE,UAAkB;IACtF,IAAI,MAAM,CAAC,gBAAgB,GAAG,UAAU,IAAI,MAAM,CAAC,gBAAgB;QAAE,OAAO;IAC5E,MAAM,IAAI,UAAU,CAClB,UAAU,MAAM,CAAC,KAAK,oBAAoB,MAAM,CAAC,gBAAgB,IAAI;QACnE,GAAG,MAAM,CAAC,gBAAgB,GAAG,UAAU,UAAU,MAAM,CAAC,gBAAgB,gBAAgB;QACxF,iFAAiF,CACpF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,UAAU,CACjB,GAA2B,EAC3B,WAAmB,EACnB,OAAuC;IAEvC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,kBAAkB,CAAC,WAAW,GAAG,eAAe,EAAE,GAAG,WAAW,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC7F,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QAC7B,MAAM,IAAI,UAAU,CAClB,aAAa,GAAG,CAAC,MAAM,qCAAqC,WAAW,mBAAmB;YACxF,8EAA8E;YAC9E,yBAAyB,CAC5B,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;AACzE,CAAC;AAED,2FAA2F;AAC3F,SAAS,WAAW,CAAC,KAAiB,EAAE,GAAe,EAAE,IAAsB;IAC7E,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACnF,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;IAC9B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,CAAC,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;QACrD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,sEAAsE;YACtE,wFAAwF;YACxF,+EAA+E;YAC/E,4EAA4E;YAC5E,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,IAAI,CAAC,CAAC,CAAC;YAC7C,IAAI,KAAK,GAAG,MAAM;gBAAE,KAAK,IAAI,OAAO,CAAC;YACrC,IAAI,KAAK,GAAG,GAAG,IAAI,KAAK,GAAG,IAAI;gBAAE,UAAU,EAAE,CAAC;YAC9C,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;YACnB,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,KAAiB,EAAE,GAAe,EAAE,IAAsB;IAC7E,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACnF,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;IAC9B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,CAAC,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;QACrD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YACvB,+DAA+D;YAC/D,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAE,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAE,IAAI,EAAE,CAAC,CAAC;YACrE,IAAI,KAAK,GAAG,QAAQ;gBAAE,KAAK,IAAI,SAAS,CAAC;YACzC,IAAI,KAAK,GAAG,GAAG,IAAI,KAAK,GAAG,IAAI;gBAAE,UAAU,EAAE,CAAC;YAC9C,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC;YACnB,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAiB,EACjB,WAAuB,EACvB,OAAoB,EACpB,WAAmB,EACnB,GAAgB,EAChB,OAA4B;IAE5B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC7C,iBAAiB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAEhD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC;IAC7C,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACjD,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,cAAc,CAAC,CAAC;IAE1E,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,GAAG,gBAAgB,CAAC;IACrD,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,IAAI,GAAqB;QAC7B,WAAW,EAAE,OAAO,CAAC,KAAK;QAC1B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,gFAAgF;QAChF,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,gBAAgB;QAChB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC;QAClE,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,cAAc,CAAC;KACpE,CAAC;IAEF,MAAM,sBAAsB,GAC1B,cAAc,KAAK,CAAC;QAClB,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;QACzC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAE9C,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAiB,EACjB,WAAuB,EACvB,OAAoB,EACpB,WAAmB,EACnB,GAAgB,EAChB,OAA4B;IAE5B,OAAO,oBAAoB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;AAC/F,CAAC"}

package/dist/decode/physical.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Digital counts to physical units.
+ *
+ * Layer 3. Sole owner of the scaling expression. The expression is PINNED — see `toPhysical`
+ * before changing anything in this file.
+ *
+ * Also home to `clampToDigitalRange`, which is a cross-validation tool and never part of a
+ * read: EDFlib clamps silently when it loads samples, edfcore does not, and reproducing that
+ * behaviour has to be something a caller asks for explicitly.
+ */
+import type { EdfSignal } from '../types.js';
+import type { MaterializeOptions } from './digital.js';
+export type { MaterializeOptions } from './digital.js';
+/**
+ * `physical = bitValue * (offset + digital)`, in float64 throughout.
+ *
+ * THIS EXPRESSION IS PINNED AND MUST NOT BE "SIMPLIFIED". It is numerically worse than
+ * `physicalMinimum + (digital - digitalMinimum) * gain`, and that is not an accident: it is
+ * EDFlib's exact form, kept verbatim so edfcore reproduces pyEDFlib/EDFlib float64 output
+ * bit for bit. The two forms disagree by up to ~9.3e-10 LSB — ten orders of magnitude below
+ * the quantisation floor, and on asymmetric ranges they differ on nearly half the samples by
+ * one ULP. Rewriting this line breaks the golden-value tests, and rightly so.
+ *
+ * Throws `EdfScalingError` when `signal.scale` is `undefined`. edfcore never fabricates a gain,
+ * and `decodeDigital` keeps working on such a signal.
+ */
+export declare function toPhysical(signal: EdfSignal, digital: ArrayLike<number>, out?: Float64Array, options?: MaterializeOptions): Float64Array;
+/**
+ * Clamp to the declared digital range. POST-HOC ONLY — nothing on the read path calls this.
+ *
+ * It exists to reproduce a clamping consumer (EDFlib clamps silently on read; edfcore does not)
+ * when cross-validating against one. Clamping to `[min(digMin, digMax), max(digMin, digMax)]`
+ * rather than to `[digMin, digMax]` matters for an inverted declaration, where the naive bounds
+ * are empty and collapse every sample onto a single value.
+ */
+export declare function clampToDigitalRange(signal: EdfSignal, digital: Int32Array, out?: Int32Array, options?: MaterializeOptions): Int32Array;
+//# sourceMappingURL=physical.d.ts.map

package/dist/decode/physical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physical.d.ts","sourceRoot":"","sources":["../../src/decode/physical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAqB,SAAS,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAsJvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC,EAC1B,GAAG,CAAC,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,YAAY,CAad;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,GAAG,CAAC,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,UAAU,CAsBZ"}