edfcore 0.1.0

package/dist/header/lookup.js

@@ -0,0 +1,67 @@
+/**
+ * Finding a signal by name.
+ *
+ * Layer 2. Two functions and a predicate, and the reason they exist rather than being left to
+ * the caller: deleting name lookup does not delete `signals.find(s => s.label === label)`, which
+ * silently returns the first of a duplicate pair. CHB-MIT ships `'T8-P8'` twice, and picking one
+ * of them by accident is how the wrong channel ends up in a paper.
+ *
+ * Matching is exact on the TRIMMED label and is case-sensitive. Nothing else is normalised: EDF
+ * labels are electrode names, `'Fp1'` and `'FP1'` are written by different systems, and edfcore
+ * has no montage vocabulary to decide they are the same thing.
+ */
+import { trimEdfField } from '../bytes/latin1.js';
+import { BDF_ANNOTATIONS_LABEL, EDF_ANNOTATIONS_LABEL } from '../constants.js';
+import { EdfAmbiguousChannelError, EdfChannelNotFoundError } from '../errors.js';
+/**
+ * True for the two reserved annotation labels, matched on the trimmed text and case-sensitively.
+ *
+ * Both are accepted for either family: the label identifies the channel's ROLE, and a BDF+ file
+ * written by an EDF+ library carries `'EDF Annotations'` — refusing to recognise it there would
+ * expose a text channel as if it held samples.
+ */
+export function isAnnotationLabel(label) {
+    const trimmed = trimEdfField(label);
+    return trimmed === EDF_ANNOTATIONS_LABEL || trimmed === BDF_ANNOTATIONS_LABEL;
+}
+/** Every signal with this label, in signal order. Empty when none matches. */
+export function findSignals(header, label) {
+    const wanted = trimEdfField(label);
+    return Object.freeze(header.signals.filter((signal) => signal.label === wanted));
+}
+function quoteLabels(header) {
+    return header.signals.map((signal) => JSON.stringify(signal.label)).join(', ');
+}
+/**
+ * One signal, by index or by label.
+ *
+ * A numeric selector indexes `header.signals` directly. A label that matches nothing throws
+ * `EdfChannelNotFoundError` carrying every available label; a label that matches more than one
+ * signal throws `EdfAmbiguousChannelError` carrying the indices, because there is no answer
+ * edfcore could return that would not be a guess.
+ */
+export function getSignal(header, selector) {
+    if (typeof selector === 'number') {
+        const signal = header.signals[selector];
+        if (signal !== undefined)
+            return signal;
+        throw new EdfChannelNotFoundError(`signal index ${selector} is outside the ${header.signals.length} signals this file ` +
+            `declares. Labels, in signal order: ${quoteLabels(header)}. Next: pass an index in ` +
+            `0..${header.signals.length - 1}, or a label.`, { selector, availableLabels: header.signals.map((signal) => signal.label) });
+    }
+    const matches = findSignals(header, selector);
+    const first = matches[0];
+    if (first === undefined) {
+        throw new EdfChannelNotFoundError(`no signal is labelled ${JSON.stringify(trimEdfField(selector))} in this file. Labels, ` +
+            `in signal order: ${quoteLabels(header)}. Matching is exact on the trimmed label and ` +
+            'is case-sensitive. Next: pass one of those labels, or select by index.', { selector, availableLabels: header.signals.map((signal) => signal.label) });
+    }
+    if (matches.length === 1)
+        return first;
+    const matchingIndices = matches.map((signal) => signal.index);
+    throw new EdfAmbiguousChannelError(`label ${JSON.stringify(trimEdfField(selector))} matches ${matches.length} signals ` +
+        `(indices ${matchingIndices.join(', ')}), so getSignal cannot choose one — returning the ` +
+        'first is how the wrong channel ends up in a paper. Next: call findSignals() to get them ' +
+        'all, or select by index.', { label: trimEdfField(selector), matchingIndices });
+}
+//# sourceMappingURL=lookup.js.map

package/dist/header/lookup.js.map

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

package/dist/header/parse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `parseHeader` — the orchestrator.
+ *
+ * Layer 2. Sole owner of header validation ORDER. Every check below is numbered, and the numbers
+ * are the contract: under `strict` the FIRST would-be diagnostic throws, so the order decides
+ * which error a broken file reports, and a test pins it. Moving a check is a behavioural change
+ * even when every individual check is unaltered.
+ *
+ * The order is not arbitrary. Each step establishes something the next one needs:
+ *
+ *   1. at least 256 bytes            8. the record size, hence the file geometry
+ *   2. the variant, hence sample width    9. the record count, which needs 8 and the source size
+ *   3. ns, before any ns-sized work      10. the EDF+ annotations requirement
+ *   4. the whole header is present       11. the text fields, which nothing else depends on
+ *   5. the declared header size (loses)
+ *   6. the record duration
+ *   7. the per-signal blocks
+ *
+ * `sourceByteLength` is required and positional because two of those steps genuinely need the
+ * size of the file the header came from: recovering `recordCount = -1`, and telling a truncated
+ * file from a complete one.
+ */
+import type { EdfHeader, ParseOptions } from '../types.js';
+/**
+ * Parse an EDF/BDF header.
+ *
+ * `headerBytes` must hold at least `256 * (ns + 1)` bytes; anything beyond that is ignored, so a
+ * caller that over-read is free to pass its whole buffer. `sourceByteLength` is the size of the
+ * file those bytes came from — pass `bytes.byteLength` for an in-memory file.
+ */
+export declare function parseHeader(headerBytes: Uint8Array, sourceByteLength: number, options?: ParseOptions): EdfHeader;
+//# sourceMappingURL=parse.d.ts.map

package/dist/header/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/header/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAoK3D;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,UAAU,EACvB,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,YAAY,GACrB,SAAS,CA6LX"}

package/dist/header/parse.js

@@ -0,0 +1,319 @@
+/**
+ * `parseHeader` — the orchestrator.
+ *
+ * Layer 2. Sole owner of header validation ORDER. Every check below is numbered, and the numbers
+ * are the contract: under `strict` the FIRST would-be diagnostic throws, so the order decides
+ * which error a broken file reports, and a test pins it. Moving a check is a behavioural change
+ * even when every individual check is unaltered.
+ *
+ * The order is not arbitrary. Each step establishes something the next one needs:
+ *
+ *   1. at least 256 bytes            8. the record size, hence the file geometry
+ *   2. the variant, hence sample width    9. the record count, which needs 8 and the source size
+ *   3. ns, before any ns-sized work      10. the EDF+ annotations requirement
+ *   4. the whole header is present       11. the text fields, which nothing else depends on
+ *   5. the declared header size (loses)
+ *   6. the record duration
+ *   7. the per-signal blocks
+ *
+ * `sourceByteLength` is required and positional because two of those steps genuinely need the
+ * size of the file the header came from: recovering `recordCount = -1`, and telling a truncated
+ * file from a complete one.
+ */
+import { trimEdfField } from '../bytes/latin1.js';
+import { copyBytes } from '../bytes/view.js';
+import { EDF_HEADER_BLOCK_BYTES, EDF_RECOMMENDED_MAX_RECORD_BYTES, HEADER_FIELDS, SIGNAL_FIELD_WIDTHS, } from '../constants.js';
+import { DiagnosticSink, fatalError } from '../diagnostics/collector.js';
+import { parseUnsignedTicks, secondsToTicks } from '../tal/ticks.js';
+import { resolveStartTime } from './dates.js';
+import { checkDeclaredHeaderByteLength, describeFixedField, fixedFieldSpecReference, parseDeclaredRecordCount, parseRecordDuration, parseSignalCount, readRawHeaderFields, reportNonAsciiHeaderFields, } from './fields.js';
+import { parsePatientId, parseRecordingId } from './identification.js';
+import { buildSignals, parseSignalHeaders, signalFieldOffset } from './signals.js';
+import { detectVariant } from './variant.js';
+/**
+ * How many data records the file actually contains.
+ *
+ * Four outcomes, and every one of them is reported: the count was unknown and was recovered from
+ * the source length; the file is shorter than the count claims; the file ends part-way through a
+ * record; the file carries bytes beyond the records it declares. Nothing is ever padded into
+ * existence — a record that is not entirely present is not a record.
+ */
+function resolveRecordCount(input, sink) {
+    const { raw, declared, headerByteLength, recordByteLength, sourceByteLength } = input;
+    const availableDataBytes = Math.max(0, sourceByteLength - headerByteLength);
+    const wholeRecords = Math.floor(availableDataBytes / recordByteLength);
+    const partialBytes = availableDataBytes - wholeRecords * recordByteLength;
+    const description = describeFixedField('recordCount');
+    const specReference = fixedFieldSpecReference('recordCount');
+    const field = 'recordCount';
+    const byteOffset = HEADER_FIELDS.recordCount.offset;
+    const byteLength = HEADER_FIELDS.recordCount.length;
+    const reportPartialFinalRecord = () => {
+        if (partialBytes === 0)
+            return;
+        sink.report({
+            code: 'PARTIAL_FINAL_RECORD',
+            message: `the source ends ${partialBytes} bytes into data record ${wholeRecords}, which is ` +
+                `${recordByteLength} bytes long, so that record is incomplete. ${specReference}: every ` +
+                `data record in a file has the same size. Next: header.recordCount is ${wholeRecords} ` +
+                'and only whole records are exposed — edfcore never zero-pads a record into existence, ' +
+                'because the padding would decode as real samples.',
+            field: 'dataRecords',
+            byteOffset: headerByteLength + wholeRecords * recordByteLength,
+            byteLength: partialBytes,
+            raw,
+            expected: `${recordByteLength} bytes`,
+            actual: `${partialBytes} bytes`,
+            specReference,
+        });
+    };
+    // -1 is the sanctioned "the writer never closed the file" value; an unreadable field and any
+    // other negative count mean the same thing, and the same recovery is the truthful answer.
+    if (Number.isNaN(declared) || declared < 0) {
+        const declaredText = Number.isNaN(declared)
+            ? ', which is not a whole number of data records'
+            : `, i.e. ${declared}`;
+        sink.report({
+            code: 'RECORD_COUNT_RECOVERED',
+            message: `${description} is ${JSON.stringify(raw)}${declaredText}, so the count was recovered ` +
+                `from the source length: floor((${sourceByteLength} - ${headerByteLength}) / ` +
+                `${recordByteLength}) = ${wholeRecords} whole data records. ${specReference}: -1 means ` +
+                'the writer never closed the file. Next: header.recordCount is ' +
+                `${wholeRecords} and header.recordCountSource is "sourceByteLength"; if that looks ` +
+                "wrong, check that parseHeader's sourceByteLength argument is the true file size.",
+            field,
+            byteOffset,
+            byteLength,
+            raw,
+            expected: 'a whole number of data records',
+            actual: String(declared),
+            specReference,
+        });
+        reportPartialFinalRecord();
+        return { recordCount: wholeRecords, recordCountSource: 'sourceByteLength' };
+    }
+    if (declared > wholeRecords) {
+        sink.report({
+            code: 'TRUNCATED_FILE',
+            message: `${description} is ${JSON.stringify(raw)}, i.e. ${declared} data records of ` +
+                `${recordByteLength} bytes, which needs ` +
+                `${headerByteLength + declared * recordByteLength} bytes; the source is ` +
+                `${sourceByteLength} bytes and holds ${wholeRecords} whole records. ${specReference}. ` +
+                `Next: header.recordCount is ${wholeRecords} and header.recordCountSource is ` +
+                '"sourceByteLength"; the missing records are not readable, and edfcore will not ' +
+                'fabricate them.',
+            field,
+            byteOffset,
+            byteLength,
+            raw,
+            expected: `at most ${wholeRecords} data records`,
+            actual: String(declared),
+            specReference,
+        });
+        reportPartialFinalRecord();
+        return { recordCount: wholeRecords, recordCountSource: 'sourceByteLength' };
+    }
+    const extraBytes = availableDataBytes - declared * recordByteLength;
+    if (extraBytes > 0) {
+        if (declared === wholeRecords) {
+            reportPartialFinalRecord();
+        }
+        else {
+            sink.report({
+                code: 'TRAILING_BYTES',
+                message: `the source carries ${extraBytes} bytes beyond the ${declared} data records the ` +
+                    `header declares, which end at byte ${headerByteLength + declared * recordByteLength} ` +
+                    `of ${sourceByteLength}. ${specReference}. Next: those bytes are never decoded; ` +
+                    'header.recordCount stays at the declared count and header.dataByteLength counts ' +
+                    'only the declared records.',
+                field: 'dataRecords',
+                byteOffset: headerByteLength + declared * recordByteLength,
+                byteLength: extraBytes,
+                raw,
+                expected: `${declared * recordByteLength} data bytes`,
+                actual: `${availableDataBytes} data bytes`,
+                specReference,
+            });
+        }
+    }
+    return { recordCount: declared, recordCountSource: 'headerField' };
+}
+/**
+ * The record duration in exact 100 ns ticks.
+ *
+ * Taken from the DIGITS on disk rather than from the parsed float, so `'0.1'` is 1000000 ticks
+ * and not whatever `0.1 * 1e7` rounds to. `tal/ticks.ts` owns that conversion; it is listed a
+ * layer above this one but depends on nothing except the tick constant, and reimplementing exact
+ * decimal-to-tick parsing here to respect the table would be the worse trade.
+ *
+ * The float path is the fallback for the spellings the tick grammar does not admit — `'+1'`,
+ * `'1E3'` — which `parseRecordDuration` has already accepted and proved finite and non-negative.
+ */
+function recordDurationTicksOf(raw, seconds) {
+    const exact = parseUnsignedTicks(trimEdfField(raw));
+    return exact.ok ? exact.ticks : secondsToTicks(seconds);
+}
+/**
+ * Parse an EDF/BDF header.
+ *
+ * `headerBytes` must hold at least `256 * (ns + 1)` bytes; anything beyond that is ignored, so a
+ * caller that over-read is free to pass its whole buffer. `sourceByteLength` is the size of the
+ * file those bytes came from — pass `bytes.byteLength` for an in-memory file.
+ */
+export function parseHeader(headerBytes, sourceByteLength, options) {
+    // A caller bug, not a file defect, so it is a plain RangeError: EdfFormatError would claim the
+    // bytes are wrong when what is wrong is the number describing them.
+    if (!Number.isSafeInteger(sourceByteLength) || sourceByteLength < 0) {
+        throw new RangeError(`parseHeader(): sourceByteLength must be a non-negative safe integer, received ` +
+            `${sourceByteLength}. Next: pass the byte length of the whole file — bytes.byteLength ` +
+            'for an in-memory file, or source.byteLength for a ByteSource.');
+    }
+    const sink = new DiagnosticSink(options);
+    // ---- 1. The fixed header must be present at all. --------------------------------------
+    if (headerBytes.length < EDF_HEADER_BLOCK_BYTES) {
+        throw fatalError({
+            code: 'SOURCE_TOO_SMALL',
+            message: `the header is ${headerBytes.length} bytes, but every EDF and BDF file begins with a ` +
+                `${EDF_HEADER_BLOCK_BYTES}-byte fixed header. EDF specification, header record bytes ` +
+                '0-255. Next: check that the whole file reached edfcore — an empty file, a truncated ' +
+                'download and a directory read all land here.',
+            field: 'header',
+            byteOffset: 0,
+            byteLength: headerBytes.length,
+            expected: `at least ${EDF_HEADER_BLOCK_BYTES} bytes`,
+            actual: `${headerBytes.length} bytes`,
+            specReference: 'EDF specification, header record bytes 0-255',
+        });
+    }
+    const raw = readRawHeaderFields(headerBytes);
+    // ---- 2. Version block and reserved marker: the family, the sample width, the dialect. ----
+    const variant = detectVariant(headerBytes, sink);
+    // ---- 3. ns, before any ns-sized allocation and before trusting the field at offset 184. --
+    const signalCount = parseSignalCount(raw.signalCount, sink);
+    // ---- 4. The whole header must be present, now that its size is known. -------------------
+    const headerByteLength = EDF_HEADER_BLOCK_BYTES * (signalCount + 1);
+    if (headerBytes.length < headerByteLength) {
+        throw fatalError({
+            code: 'SOURCE_TOO_SMALL',
+            message: `the header of a file declaring ${signalCount} signals is ${EDF_HEADER_BLOCK_BYTES} * ` +
+                `(${signalCount} + 1) = ${headerByteLength} bytes, but only ${headerBytes.length} ` +
+                'bytes are available. EDF specification, header record. Next: read ' +
+                `${headerByteLength} bytes from offset 0 and parse those; if the file itself is that ` +
+                'short, the signal count at offset 252 is not the one the file was written with.',
+            field: 'header',
+            byteOffset: 0,
+            byteLength: headerBytes.length,
+            expected: `${headerByteLength} bytes`,
+            actual: `${headerBytes.length} bytes`,
+            specReference: 'EDF specification, header record bytes 184-191 (number of bytes in header)',
+        });
+    }
+    // ---- 5. The declared header size. The computed one always wins. -------------------------
+    const declaredHeaderByteLength = checkDeclaredHeaderByteLength(raw.headerByteLength, headerByteLength, sink);
+    // ---- 6. The record duration. May be fractional, and may legitimately be 0. --------------
+    const recordDurationSeconds = parseRecordDuration(raw.recordDuration, sink);
+    const recordDurationTicks = recordDurationTicksOf(raw.recordDuration, recordDurationSeconds);
+    // ---- 7. The field-major per-signal blocks. ----------------------------------------------
+    const parsed = parseSignalHeaders({ headerBytes, signalCount, variant, recordDurationSeconds }, sink);
+    const recordByteLength = parsed.recordByteLength;
+    // ---- 8. The record size, which every data offset in the file steps by. ------------------
+    if (recordByteLength === 0) {
+        const samplesBlockOffset = signalFieldOffset('samplesPerRecord', signalCount, 0);
+        throw fatalError({
+            code: 'RECORD_SIZE_ZERO',
+            message: `every one of the ${signalCount} signals declares 0 samples per data record, so a data ` +
+                'record is 0 bytes long and the file has no record size to step by — record N and ' +
+                'record N+1 would begin at the same byte. EDF specification, data records. Next: the ' +
+                `per-signal sample counts live at offset ${samplesBlockOffset}, ` +
+                `${SIGNAL_FIELD_WIDTHS.samplesPerRecord} bytes per signal; header.raw keeps them as ` +
+                'written.',
+            field: 'samplesPerRecord',
+            byteOffset: samplesBlockOffset,
+            byteLength: signalCount * SIGNAL_FIELD_WIDTHS.samplesPerRecord,
+            expected: 'at least one signal with a non-zero number of samples per record',
+            actual: '0 bytes per data record',
+            specReference: 'EDF specification, data records',
+        });
+    }
+    if (recordByteLength > EDF_RECOMMENDED_MAX_RECORD_BYTES) {
+        sink.report({
+            code: 'RECORD_SIZE_ABOVE_RECOMMENDED',
+            message: `a data record is ${recordByteLength} bytes (${variant.bytesPerSample} bytes per ` +
+                `sample x ${recordByteLength / variant.bytesPerSample} samples), above the ` +
+                `${EDF_RECOMMENDED_MAX_RECORD_BYTES}-byte record size the EDF specification ` +
+                'recommends. EDF specification, data records (recommended maximum record size). Next: ' +
+                'nothing — the file is read normally, but reads are record-aligned, so this is also ' +
+                'the smallest amount of data any read can return.',
+            field: 'recordByteLength',
+            expected: `at most ${EDF_RECOMMENDED_MAX_RECORD_BYTES} bytes`,
+            actual: `${recordByteLength} bytes`,
+            specReference: 'EDF specification, data records',
+        });
+    }
+    // ---- 9. The record count, recovered or verified against the real file size. -------------
+    const declaredRecordCount = parseDeclaredRecordCount(raw.recordCount, sink);
+    const { recordCount, recordCountSource } = resolveRecordCount({
+        raw: raw.recordCount,
+        declared: declaredRecordCount,
+        headerByteLength,
+        recordByteLength,
+        sourceByteLength,
+    }, sink);
+    // ---- 10. EDF+ without an annotations signal has no per-record timing to report. ---------
+    if (variant.isPlus && parsed.annotationSignalIndices.length === 0) {
+        throw fatalError({
+            code: 'EDFPLUS_WITHOUT_ANNOTATION_SIGNAL',
+            message: `the reserved field at offset ${HEADER_FIELDS.reserved.offset} declares ` +
+                `${JSON.stringify(variant.reservedMarker ?? '')} but no signal is labelled ` +
+                `${JSON.stringify(variant.annotationsLabel)}. EDF+ specification 2.2.4: every data ` +
+                'record of an EDF+ file carries a timekeeping TAL in an annotations signal, and that ' +
+                'is the only place a record start time exists. Without it every time edfcore reported ' +
+                'would be invented. Next: read the samples as plain ' +
+                `${variant.family} by clearing the EDF+ marker in the reserved field, or find the ` +
+                'writer that dropped the annotations channel.',
+            field: 'reserved',
+            byteOffset: HEADER_FIELDS.reserved.offset,
+            byteLength: HEADER_FIELDS.reserved.length,
+            raw: raw.reserved,
+            expected: `a signal labelled ${JSON.stringify(variant.annotationsLabel)}`,
+            actual: `${signalCount} signals, none of them annotations`,
+            specReference: 'EDF+ specification 2.2.4 (the "EDF Annotations" signal)',
+        });
+    }
+    // ---- 11. The text fields. Nothing above depends on them. --------------------------------
+    reportNonAsciiHeaderFields(headerBytes, sink);
+    const patient = parsePatientId(raw.patientId, { edfPlus: variant.isPlus }, sink);
+    const recording = parseRecordingId(raw.recordingId, { edfPlus: variant.isPlus }, sink);
+    const startTime = resolveStartTime({
+        rawStartDate: raw.startDate,
+        rawStartTime: raw.startTime,
+        recordingIdDate: recording.startDate,
+    }, sink);
+    return {
+        variant: variant.variant,
+        continuity: variant.continuity,
+        bytesPerSample: variant.bytesPerSample,
+        headerByteLength,
+        declaredHeaderByteLength,
+        recordByteLength,
+        dataByteLength: recordCount * recordByteLength,
+        recordDurationSeconds,
+        recordDurationTicks,
+        recordCount,
+        declaredRecordCount,
+        recordCountSource,
+        startTime,
+        patient,
+        recording,
+        signals: buildSignals(parsed.signals, recordCount),
+        dataSignalIndices: parsed.dataSignalIndices,
+        annotationSignalIndices: parsed.annotationSignalIndices,
+        reserved: raw.reserved,
+        raw,
+        // A copy, not a view: the caller owns the buffer it read into and is free to reuse it, and
+        // a header that quietly changed under a hexdump would be worse than no hexdump.
+        rawBytes: copyBytes(headerBytes, 0, headerByteLength),
+        diagnostics: sink.diagnostics,
+    };
+}
+//# sourceMappingURL=parse.js.map

package/dist/header/parse.js.map

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

package/dist/header/scale.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Digital-to-physical scale, and the decision to refuse one.
+ *
+ * Layer 2. Sole owner of `EdfScale` construction and of the four conditions under which a
+ * signal gets `scale: undefined` instead of a fabricated gain.
+ *
+ * The expression is EDFlib's, verbatim:
+ *
+ *     bitValue = (physicalMaximum - physicalMinimum) / (digitalMaximum - digitalMinimum)
+ *     offset   = physicalMaximum / bitValue - digitalMaximum
+ *     physical = bitValue * (offset + digital)
+ *
+ * The textbook `physicalMinimum + (digital - digitalMinimum) * gain` form is numerically
+ * *better* and is deliberately not used: it shifts up to ~45% of samples by one ULP on
+ * asymmetric ranges, which would forfeit float64 bit-parity with pyEDFlib for a divergence ten
+ * orders of magnitude below the quantisation floor. Do not "simplify" this.
+ *
+ * `physicalMinimum > physicalMaximum` is legal — it is how a negative amplifier gain is
+ * written — and produces a negative `bitValue`. The two are never swapped: a silent polarity
+ * flip is a clinically wrong result that looks perfectly normal.
+ */
+import type { DiagnosticSink } from '../diagnostics/collector.js';
+import type { EdfRawSignalFields, EdfScale } from '../types.js';
+/** Byte offsets of the per-signal fields a scaling diagnostic points at. */
+export interface ScaleFieldOffsets {
+    readonly physicalDimension: number;
+    readonly physicalMinimum: number;
+    readonly physicalMaximum: number;
+    readonly digitalMinimum: number;
+    readonly digitalMaximum: number;
+}
+export interface ScaleInput {
+    readonly signalIndex: number;
+    /** Trimmed label, for the message. */
+    readonly label: string;
+    /** Physical dimension exactly as written; `'Filtered'` is refused after trimming. */
+    readonly physicalDimension: string;
+    readonly physicalMinimum: number;
+    readonly physicalMaximum: number;
+    readonly digitalMinimum: number;
+    readonly digitalMaximum: number;
+    /** The raw per-signal field text, so a message can quote the bytes as written. */
+    readonly raw: EdfRawSignalFields | undefined;
+    /** Where those fields live in the header. */
+    readonly byteOffsets: ScaleFieldOffsets | undefined;
+}
+/**
+ * Collapse the encodings of micro to `'u'` so units can be compared.
+ *
+ * For comparison ONLY: `signal.physicalDimension` stays exactly as the file wrote it. Nothing
+ * else is touched — case is meaningful (`mV` is not `MV`), and edfcore does not normalise units
+ * to SI volts.
+ */
+export declare function normaliseUnit(physicalDimension: string): string;
+/**
+ * The scale for one signal, or `undefined` when edfcore refuses to invent one.
+ *
+ * The refusals are checked in this fixed order: degenerate digital range, degenerate physical
+ * range, inverted digital range, log-transformed channel, and finally a derived gain that is not
+ * a usable float64 number. Each is deferred-fatal — `decodeDigital` keeps working on the signal
+ * and `toPhysical` throws `EdfScalingError`.
+ *
+ * A non-finite input returns `undefined` without a diagnostic: the only way to get here with
+ * one is a numeric field that failed its grammar, which the caller has already reported
+ * against the field itself.
+ */
+export declare function buildScale(input: ScaleInput, sink: DiagnosticSink): EdfScale | undefined;
+//# sourceMappingURL=scale.d.ts.map

package/dist/header/scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scale.d.ts","sourceRoot":"","sources":["../../src/header/scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAYhE,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC7C,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAE/D;AA6CD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,GAAG,QAAQ,GAAG,SAAS,CA4IxF"}