edfcore 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarthak Tayal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# edfcore
+
+edfcore reads EDF, EDF+, BDF and BDF+ biosignal files in TypeScript, in the browser and in
+Node. Real random access, no dependencies.
+
+```bash
+npm install edfcore
+```
+
+## How do I read an EDF file in JavaScript?
+
+Open a source, pick a signal, read a time window, convert it to physical units. In the browser,
+a `File` from an `<input type="file">` works directly:
+
+```ts
+import { openEdf, blobSource, getSignal, readWindow, toPhysical } from 'edfcore';
+
+const recording = await openEdf(blobSource(file));
+const fp1 = getSignal(recording.header, 'Fp1');
+
+const [chunk] = await readWindow(recording, {
+  signalIndices: [fp1.index],
+  startSeconds: 30,
+  durationSeconds: 10,
+});
+
+const microvolts = toPhysical(fp1, chunk.signals[0].digital);   // Float64Array
+```
+
+In Node, swap the source and nothing else changes:
+
+```ts
+import { openEdf, getSignal, readWindow, toPhysical } from 'edfcore';
+import { fileSource } from 'edfcore/node';
+
+const recording = await openEdf(await fileSource('./overnight.edf'));
+
+console.log(recording.header.variant);                  // 'EDF+C'
+console.log(recording.header.signals.map((s) => s.label));
+console.log(recording.timeline.spanSeconds);
+```
+
+Reading those ten seconds out of a twelve-hour recording reads roughly ten seconds' worth of
+bytes. Nothing loads the whole file.
+
+Events come from the same recording, with exact times:
+
+```ts
+import { readAnnotations } from 'edfcore';
+
+const { annotations } = await readAnnotations(recording, {
+  start: 0,
+  count: recording.header.recordCount,
+});
+
+for (const event of annotations) {
+  console.log(event.onsetSecondsFromFirstRecord, event.durationSeconds, event.text);
+}
+```
+
+> **Status: 0.1.0, early.** edfcore runs 1,100+ tests on generated fixtures, and it's checked
+> against public corpora it didn't author: the EDF, EDF+ and 24-bit BDF+ test files from
+> teuniz.net, and PhysioNet's sleep-edfx (a real 22-hour polysomnography recording and its
+> sleep-staging file). Those checks are numeric. Channels labelled `sine 8.5 Hz` decode to
+> 8.5 Hz at their stated amplitude, the 24-bit and 16-bit paths agree on identical signals,
+> and the rectal temperature channel of a real recording reads 37 °C. Run them with
+> `npm run corpus:fetch && npm test`.
+>
+> One thing is missing: a golden-value harness comparing edfcore's float64 output against
+> pyEDFlib and MNE element by element. Until it exists, edfcore claims no numeric parity with
+> those readers. The API can still move. See [Roadmap](#roadmap).
+
+---
+
+## When to use edfcore, and when not to
+
+**Use it when** you need to read EDF, EDF+, BDF or BDF+ in JavaScript or TypeScript. That
+covers browser-based EEG and sleep viewers, Electron desktop tools, Node data pipelines, and
+research upload portals that must not send recordings to a server.
+
+**Use something else when:**
+
+- **You are already in Python.** pyEDFlib and MNE are mature, validated against enormous
+  amounts of real data, and have years of clinical use behind them. Don't port a working Python
+  pipeline to JavaScript for the sake of it.
+- **You want a whole viewer stack.** [`@epicurrents/edf-reader`](https://github.com/epicurrents/edf-reader)
+  is strong prior art and arrives with an EEG application framework attached.
+- **You need analysis, not file access.** edfcore does not filter, resample, re-reference,
+  build montages, run ICA, reject artifacts, or detect events. Those are permanent non-goals.
+- **You need to *write* EDF.** edfcore is read-only through 1.0.
+
+---
+
+## Why this exists
+
+EDF is the standard container for EEG, sleep studies, ECG and EMG. Python has excellent tooling
+for it. JavaScript didn't. This is every EDF package on npm, surveyed in mid-2026:
+
+| | Before edfcore |
+|---|---|
+| TypeScript types | No standalone reader ships them |
+| Random access | Nothing published does byte-range reads; a 24 h study is loaded whole or not at all |
+| BDF (24-bit) | No published package can read it. BioSemi hardware has no JS support |
+| EDF+D (gaps) | Unsupported or, worse, decoded as if contiguous, producing a silently wrong timeline |
+| Errors | `console.warn` and `null`, or bare thrown strings; nothing typed or located |
+| Header validation | Essentially none. No size checks, no degenerate-range checks |
+
+So people building EEG viewers don't reach for an EDF package. They hand-roll a parser and
+reproduce the same bugs.
+
+The strongest existing implementation is
+[`@epicurrents/edf-reader`](https://github.com/epicurrents/edf-reader): real TAL parsing, real
+partial reads, BDF support. It's a plugin inside an EEG application framework, so it arrives
+with that framework attached. Use it if you want a whole viewer stack. edfcore is a small,
+standalone, dependency-free file-format library you can drop into any project.
+
+---
+
+## Design in one page
+
+**A bad file either throws or reports itself.** One rule decides which. If edfcore can't
+continue without inventing something, it throws. If it can continue on what the file says, it
+records a diagnostic on the result. There's no third option, and nothing is written to the
+console.
+
+```ts
+const recording = await openEdf(source);
+for (const d of recording.header.diagnostics) {
+  console.log(d.code, d.message, d.byteOffset);   // your logger, your call
+}
+```
+
+Every diagnostic carries the field, the byte offset, the raw bytes as written, the spec clause it
+violates, and what to do next. Pass `{ strict: true }` and the first one throws instead.
+
+**Digital and physical are two functions.** `chunk.signals[i].digital` is an `Int32Array` of
+the values as stored. `toPhysical(signal, digital)` returns a `Float64Array` in the signal's own
+units. There's no `{ physical: true }` option, because it would change the return type, and no
+`Float32` output (it costs about a quarter of a quantisation step on 24-bit BDF).
+
+**Scaling can be refused.** A header that declares `digitalMinimum === digitalMaximum` defines
+no scale: the gain is a division by zero. edfcore sets `signal.scale` to `undefined`, so
+`toPhysical` throws and `strictNullChecks` catches the call you didn't guard. `decodeDigital`
+keeps working. EDFlib substitutes a gain of 1 here and returns ADC counts labelled as microvolts.
+
+**Sample rates stay per-signal.** An EDF file can hold EEG at 256 Hz, ECG at 512 Hz and
+temperature at 1 Hz. There's no recording-wide rate. Sample indexing uses `samplesPerRecord`
+rather than a floating-point rate, and `sampleRateHz` is `undefined` when the record duration is
+zero (which is legal EDF).
+
+**Event times are exact.** Annotation onsets are parsed digit by digit into `bigint`
+hundred-nanosecond ticks, not through `parseFloat`. Compare `onsetTicks`, not the float.
+
+**Gaps are structural.** `readWindow` always returns an array of chunks, one per contiguous
+run, including for continuous files. A window that falls inside a gap returns `[]`. There's no
+gap-filling and no option to enable it.
+
+**No `Date`.** EDF stores local time at the patient with no timezone, and a `Date` would apply
+the reader's zone instead. You get `EdfCalendarDate` and `EdfClockTime`, plus
+`formatStartTimeNaive()` for a zone-free ISO-like string.
+
+---
+
+## Reading data
+
+The unit of I/O is the **record range**, not the channel range. EDF interleaves every channel
+inside each data record, so there's no cheap single-channel read: asking for one channel over a
+window still reads the records containing it. `chunk.byteLength` reports the bytes actually
+read.
+
+```ts
+import { openEdf, readWindow, resolveTimeWindow } from 'edfcore';
+import { fileSource } from 'edfcore/node';
+
+const recording = await openEdf(await fileSource('./overnight.edf'));
+
+// resolveTimeWindow is pure and does no I/O, so you can audit the cost first.
+const ranges = resolveTimeWindow(recording.timeline, recording.index, 3600, 30);
+
+const chunks = await readWindow(recording, {
+  signalIndices: [0, 1, 2],
+  startSeconds: 3600,
+  durationSeconds: 30,
+});
+```
+
+Chunks are record-aligned and may be slightly wider than requested. `trimToWindow()` narrows
+them to a sample-exact window using integer arithmetic on `(record, sampleWithinRecord)` rather
+than `round(t * rate)`.
+
+### Sources
+
+One interface, four adapters, all universal:
+
+```ts
+byteSource(arrayBufferOrUint8Array)
+blobSource(fileOrBlob)                    // structural, no DOM types required
+httpSource(url, { headers })              // HTTP Range requests
+cachedSource(inner, { blockBytes })       // the only caching, opt-in
+```
+
+and from `edfcore/node`:
+
+```ts
+fileSource('./recording.edf')
+fileHandleSource(handle, byteLength)
+```
+
+Bring your own by implementing `ByteSource`, which has three members. The contract is *exactly
+`length` bytes or reject*, and edfcore verifies it on every call, including on sources you
+supplied.
+
+### Discontinuous recordings
+
+Opening a file never scans it. For EDF+D the index starts out `'probed'`, meaning record 0 and
+the last record only. It throws rather than map a timestamp to a record across an unmapped gap:
+
+```ts
+const index = await buildRecordIndex(recording, { onProgress: (done, total) => … });
+const located = { ...recording, index };
+
+index.coverage;   // 'complete'
+index.segments;   // EdfSegment[] — only defined once coverage is complete
+index.gaps;       // EdfGap[]
+```
+
+`segments` is `undefined` while coverage is `'probed'`, so no property reads as
+"continuous" before anything has checked.
+
+### Triage
+
+`inspectEdf()` reads at most 128 KiB and never throws on malformed content. It is the right first
+call for an unfamiliar file:
+
+```ts
+const { ok, variant, header, diagnostics } = await inspectEdf(source);
+console.log(formatDiagnostics(diagnostics));
+```
+
+---
+
+## What it deliberately does not do
+
+edfcore is a file-format library. It is not an EEG analysis framework. These are permanent non-goals: filtering, resampling,
+re-referencing, montages, ICA, artifact rejection, bad-channel detection, spectral analysis,
+event detection, channel-type inference from labels, unit normalisation to SI volts, and
+anything involving AI or a network service.
+
+Writing EDF is out of scope through 1.0. Producing a *correct* file is a much larger normative
+commitment than tolerating an incorrect one, and a subtly non-conformant writer would undermine
+the reason to trust the reader.
+
+---
+
+## Compatibility
+
+- **Node** ≥ 22.12.0 · **Chrome/Edge** 94+ · **Firefox** 93+ · **Safari** 15.4+
+- ESM only. `require()` works on Node ≥ 22.12 (there is no top-level `await` anywhere in the
+  module graph, which is what makes that safe).
+- Zero runtime dependencies, permanently. `edfcore/node` imports `node:fs/promises` and nothing
+  else.
+- Three entry points, no environment conditions in the exports map: `edfcore`, `edfcore/node`,
+  `edfcore/validate`.
+
+---
+
+## Roadmap
+
+**0.1 — reads everything, lies about nothing.** All six variants, the primitive/I/O/convenience
+layers, `inspectEdf`, `edfcore/validate`, six source adapters, the full diagnostic vocabulary.
+
+**Before 1.0.** Validation against public corpora (sleep-edfx, CHB-MIT, the BioSemi and
+edfplus.info test files) and a golden-value harness cross-checking physical values against
+pyEDFlib and MNE. Until that harness exists this README makes no numerical-interop claim, and it
+will not make one that a test did not produce.
+
+**Later, additive.** Min/max envelope decimation as its own type. The `edffloat` logarithmic
+inverse transform, opt-in (currently detected and rejected). BioSemi
+Status-byte helpers. JSR publication.
+
+---
+
+## Documentation
+
+The full documentation site lives in [`website/`](website/), an Astro build with twenty pages.
+It includes a **local inspector** that opens an EDF file and shows its header, channels, events
+and waveforms in your browser, with nothing uploaded.
+
+```bash
+npm install --prefix website
+npm run dev --prefix website
+```
+
+Start with **Concepts**, which is the mental model the rest of the API follows from. Then the guides (reading signals, physical values, annotations, discontinuous recordings,
+diagnostics, data sources, large files, validation), the API reference, and the background
+pages. Those include a standalone primer on the EDF format itself.
+
+### Deploying the site
+
+[`vercel.json`](vercel.json) is set up so linking this repository to Vercel works as is.
+**Leave the Root Directory as the repository root** and don't pick a framework preset. The
+build compiles the library first (the site imports `edfcore` from the parent package), then
+builds the site into `website/dist`.
+
+Nothing needs configuring for URLs: Astro reads Vercel's own production-domain variable, so the
+sitemap and canonical links are correct on the first deploy. If you later point a custom domain
+at it, set `SITE_URL` to that origin in the project's environment variables.
+
+**Design decisions** — why the API is shaped the way it is, including the choices that look
+like bugs and are not (the pinned scaling expression, `readWindow` always returning an array,
+`scale` being `undefined` rather than fabricated) are documented on the site under
+*Background → Design decisions*.
+
+- [`tests/README.md`](tests/README.md) covers how the suite builds every fixture in memory,
+  and why no binaries are committed.
+
+## License
+
+MIT © Sarthak Tayal

package/dist/bytes/latin1.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Header text decoding.
+ *
+ * Layer 0. Imports nothing. Sole owner of turning header bytes into strings.
+ *
+ * ISO-8859-1 is the identity map onto U+0000..U+00FF, so the whole decoder is
+ * `String.fromCharCode`. `TextDecoder` is banned here and everywhere outside `src/tal/`:
+ * verified on Node v24.4.0, `TextDecoder('latin1' | 'iso-8859-1' | 'ascii' | 'windows-1252')`
+ * all report `encoding === 'windows-1252'` yet decode 0x80 as U+0080, while the WHATWG
+ * Encoding Standard mandates U+20AC for those labels. The same header bytes would therefore
+ * produce different strings in Node and in a spec-compliant browser.
+ */
+/**
+ * Decode header bytes as ISO-8859-1: byte `b` becomes code point U+00`b`, always.
+ *
+ * Never `TextDecoder` — see the module comment.
+ */
+export declare function decodeHeaderLatin1(bytes: Uint8Array): string;
+/**
+ * True when the range holds any byte outside printable ASCII 32..126 — the alphabet the EDF
+ * spec allows in a header field. Drives `NON_ASCII_HEADER_FIELD`, which is a warning: the
+ * field still decodes truthfully as Latin-1, and real equipment writes accented names and a
+ * bare 0xB5 for micro.
+ *
+ * Trailing NUL padding counts, deliberately: it is outside the alphabet too, and the caller
+ * that wants to tolerate it can check the padding itself.
+ */
+export declare function hasNonPrintableAscii(bytes: Uint8Array): boolean;
+/**
+ * Strip EDF field padding: spaces and NULs, from both ends.
+ *
+ * EDF pads on the RIGHT with spaces, so trailing padding is the expected case. Leading
+ * padding is stripped as well, and that choice is deliberate: a label written `'  Fp1'`
+ * names the same electrode as `'Fp1   '`, and text fields are compared, not measured. No
+ * evidence is lost by it — every field is also exposed raw and untrimmed, and for numeric
+ * fields the non-conformance is reported separately by `parseEdfInteger`/`parseEdfNumber`,
+ * which read the untrimmed string.
+ *
+ * Only 0x20 and 0x00 are stripped. A trailing TAB or CR is not padding, it is content the
+ * file should not contain, and hiding it here would hide it from `NON_ASCII_HEADER_FIELD`.
+ */
+export declare function trimEdfField(text: string): string;
+//# sourceMappingURL=latin1.d.ts.map

package/dist/bytes/latin1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"latin1.d.ts","sourceRoot":"","sources":["../../src/bytes/latin1.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAsBH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAO5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAK/D;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/dist/bytes/latin1.js

@@ -0,0 +1,84 @@
+/**
+ * Header text decoding.
+ *
+ * Layer 0. Imports nothing. Sole owner of turning header bytes into strings.
+ *
+ * ISO-8859-1 is the identity map onto U+0000..U+00FF, so the whole decoder is
+ * `String.fromCharCode`. `TextDecoder` is banned here and everywhere outside `src/tal/`:
+ * verified on Node v24.4.0, `TextDecoder('latin1' | 'iso-8859-1' | 'ascii' | 'windows-1252')`
+ * all report `encoding === 'windows-1252'` yet decode 0x80 as U+0080, while the WHATWG
+ * Encoding Standard mandates U+20AC for those labels. The same header bytes would therefore
+ * produce different strings in Node and in a spec-compliant browser.
+ */
+/** Padding bytes an EDF field may carry. Space is the spec's; NUL is what writers emit. */
+const CHAR_NUL = 0x00;
+const CHAR_SPACE = 0x20;
+/** The spec's legal header alphabet. Anything outside it is Latin-1 in practice. */
+const PRINTABLE_ASCII_MIN = 0x20;
+const PRINTABLE_ASCII_MAX = 0x7e;
+/**
+ * Well under every engine's argument-count limit (Safari's is the lowest, ~65k), so a
+ * maximal 2.56 MB header costs 625 calls rather than one that throws.
+ */
+const CHUNK_BYTES = 4096;
+function fromCharCodes(bytes) {
+    // A Uint8Array is an array-like at runtime, which is all `apply` needs; the strict
+    // `Function.prototype.apply` signature only admits `number[]`, hence the cast.
+    return String.fromCharCode.apply(null, bytes);
+}
+/**
+ * Decode header bytes as ISO-8859-1: byte `b` becomes code point U+00`b`, always.
+ *
+ * Never `TextDecoder` — see the module comment.
+ */
+export function decodeHeaderLatin1(bytes) {
+    if (bytes.length <= CHUNK_BYTES)
+        return fromCharCodes(bytes);
+    const parts = [];
+    for (let start = 0; start < bytes.length; start += CHUNK_BYTES) {
+        parts.push(fromCharCodes(bytes.subarray(start, Math.min(start + CHUNK_BYTES, bytes.length))));
+    }
+    return parts.join('');
+}
+/**
+ * True when the range holds any byte outside printable ASCII 32..126 — the alphabet the EDF
+ * spec allows in a header field. Drives `NON_ASCII_HEADER_FIELD`, which is a warning: the
+ * field still decodes truthfully as Latin-1, and real equipment writes accented names and a
+ * bare 0xB5 for micro.
+ *
+ * Trailing NUL padding counts, deliberately: it is outside the alphabet too, and the caller
+ * that wants to tolerate it can check the padding itself.
+ */
+export function hasNonPrintableAscii(bytes) {
+    for (const byte of bytes) {
+        if (byte < PRINTABLE_ASCII_MIN || byte > PRINTABLE_ASCII_MAX)
+            return true;
+    }
+    return false;
+}
+function isPadding(code) {
+    return code === CHAR_SPACE || code === CHAR_NUL;
+}
+/**
+ * Strip EDF field padding: spaces and NULs, from both ends.
+ *
+ * EDF pads on the RIGHT with spaces, so trailing padding is the expected case. Leading
+ * padding is stripped as well, and that choice is deliberate: a label written `'  Fp1'`
+ * names the same electrode as `'Fp1   '`, and text fields are compared, not measured. No
+ * evidence is lost by it — every field is also exposed raw and untrimmed, and for numeric
+ * fields the non-conformance is reported separately by `parseEdfInteger`/`parseEdfNumber`,
+ * which read the untrimmed string.
+ *
+ * Only 0x20 and 0x00 are stripped. A trailing TAB or CR is not padding, it is content the
+ * file should not contain, and hiding it here would hide it from `NON_ASCII_HEADER_FIELD`.
+ */
+export function trimEdfField(text) {
+    let start = 0;
+    let end = text.length;
+    while (end > start && isPadding(text.charCodeAt(end - 1)))
+        end--;
+    while (start < end && isPadding(text.charCodeAt(start)))
+        start++;
+    return text.slice(start, end);
+}
+//# sourceMappingURL=latin1.js.map

package/dist/bytes/latin1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"latin1.js","sourceRoot":"","sources":["../../src/bytes/latin1.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2FAA2F;AAC3F,MAAM,QAAQ,GAAG,IAAI,CAAC;AACtB,MAAM,UAAU,GAAG,IAAI,CAAC;AAExB,oFAAoF;AACpF,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACjC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB,SAAS,aAAa,CAAC,KAAiB;IACtC,mFAAmF;IACnF,+EAA+E;IAC/E,OAAO,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAA4B,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAiB;IAClD,IAAI,KAAK,CAAC,MAAM,IAAI,WAAW;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,WAAW,EAAE,CAAC;QAC/D,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAiB;IACpD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,GAAG,mBAAmB,IAAI,IAAI,GAAG,mBAAmB;YAAE,OAAO,IAAI,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,QAAQ,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACtB,OAAO,GAAG,GAAG,KAAK,IAAI,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAAE,GAAG,EAAE,CAAC;IACjE,OAAO,KAAK,GAAG,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAAE,KAAK,EAAE,CAAC;IACjE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AAChC,CAAC"}

package/dist/bytes/numbers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The two EDF numeric grammars.
+ *
+ * Layer 0. Imports nothing. Sole owner of turning an 8-byte ASCII field into a number.
+ *
+ * The spec says these fields are ASCII, left-justified and space-padded. Real files break
+ * that in every way imaginable, so parsing reports *why* it failed rather than returning NaN
+ * and leaving the caller to guess which diagnostic the bytes deserve: a comma decimal is
+ * fatal, a right-justified field is a warning, and `'20 48'` is neither of those.
+ */
+/**
+ * The outcome of parsing one numeric field.
+ *
+ * `ok === false` means `value` is meaningless — it is NaN, so a caller that ignores this flag
+ * fails loudly instead of quietly recording a plausible 0.
+ *
+ * `problem` is single-valued and ordered by how much it matters: a field that is both
+ * right-justified and comma-separated reports `'comma-decimal'`, because that is the one the
+ * caller must refuse.
+ */
+export interface EdfNumberParse {
+    readonly ok: boolean;
+    readonly value: number;
+    /** The field exactly as it was read, padding included. */
+    readonly raw: string;
+    readonly problem: 'none' | 'empty' | 'comma-decimal' | 'not-left-justified' | 'malformed';
+}
+/**
+ * Parse a field that must be a whole number: signal count, samples per record, record count,
+ * digital minimum and maximum.
+ *
+ * Exponent forms are deliberately rejected. Every field parsed by this function sizes the
+ * file geometry, and `'1E3'` in one of them is far likelier to be corruption than a writer's
+ * idea of 1000 — accepting it would turn unreadable bytes into a confidently wrong offset.
+ * `'256.0'` is rejected for the same reason.
+ */
+export declare function parseEdfInteger(raw: string): EdfNumberParse;
+/**
+ * Parse a field that may be fractional: physical minimum and maximum, record duration.
+ *
+ * Accepts a leading sign, a bare leading or trailing point, and an exponent, because writers
+ * in the wild emit `'+22'`, `'.5'`, `'1E3'` and `'-1.23E-4'`.
+ */
+export declare function parseEdfNumber(raw: string): EdfNumberParse;
+//# sourceMappingURL=numbers.d.ts.map

package/dist/bytes/numbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../../src/bytes/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,eAAe,GAAG,oBAAoB,GAAG,WAAW,CAAC;CAC3F;AAkED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAE1D"}

package/dist/bytes/numbers.js

@@ -0,0 +1,87 @@
+/**
+ * The two EDF numeric grammars.
+ *
+ * Layer 0. Imports nothing. Sole owner of turning an 8-byte ASCII field into a number.
+ *
+ * The spec says these fields are ASCII, left-justified and space-padded. Real files break
+ * that in every way imaginable, so parsing reports *why* it failed rather than returning NaN
+ * and leaving the caller to guess which diagnostic the bytes deserve: a comma decimal is
+ * fatal, a right-justified field is a warning, and `'20 48'` is neither of those.
+ */
+const CHAR_NUL = 0x00;
+const CHAR_SPACE = 0x20;
+/** No decimal point and no exponent — see `parseEdfInteger`. */
+const INTEGER_GRAMMAR = /^[+-]?[0-9]+$/;
+/** `'.5'`, `'+22'`, `'1E3'` and `'-1.23E-4'` are all emitted by real writers. */
+const NUMBER_GRAMMAR = /^[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/;
+function isPadding(code) {
+    return code === CHAR_SPACE || code === CHAR_NUL;
+}
+function failure(raw, problem) {
+    return { ok: false, value: Number.NaN, raw, problem };
+}
+function containsNul(text) {
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === CHAR_NUL)
+            return true;
+    }
+    return false;
+}
+function parseField(raw, grammar, integral) {
+    let start = 0;
+    let end = raw.length;
+    while (start < end && isPadding(raw.charCodeAt(start)))
+        start++;
+    while (end > start && isPadding(raw.charCodeAt(end - 1)))
+        end--;
+    const core = raw.slice(start, end);
+    // Distinct from malformed: an all-space field is a writer omitting a value, not corrupting
+    // one, and several fields are legally blank.
+    if (core.length === 0)
+        return failure(raw, 'empty');
+    if (core.includes(',')) {
+        // '0,5' (half) and '1,024' (a thousand and twenty-four) are indistinguishable, and
+        // substituting '.' in the second silently turns 1024 into 1.024. Fatal, never guessed.
+        // Reported as comma-decimal only when the field is otherwise numeric; 'a,b' is just junk.
+        const substituted = core.replaceAll(',', '.');
+        return failure(raw, NUMBER_GRAMMAR.test(substituted) ? 'comma-decimal' : 'malformed');
+    }
+    // Embedded whitespace inside the digits reaches here intact: '20 48' fails the grammar and
+    // is malformed, never 2048 and never 20.
+    if (!grammar.test(core))
+        return failure(raw, 'malformed');
+    const value = Number(core);
+    // Guards a digit string too long for exact float64 (integral) or one like '1e999' that
+    // overflows to Infinity. Neither can come from an 8-byte field, but this function takes a
+    // string, not a field.
+    if (integral ? !Number.isSafeInteger(value) : !Number.isFinite(value)) {
+        return failure(raw, 'malformed');
+    }
+    // The value is trustworthy; the layout is not. Leading padding means right-justified, and a
+    // NUL anywhere in the padding means the writer used the wrong pad byte. Both parse, and
+    // both are worth a NUMERIC_FIELD_NOT_LEFT_JUSTIFIED warning.
+    const leftJustified = start === 0 && !containsNul(raw.slice(end));
+    return { ok: true, value, raw, problem: leftJustified ? 'none' : 'not-left-justified' };
+}
+/**
+ * Parse a field that must be a whole number: signal count, samples per record, record count,
+ * digital minimum and maximum.
+ *
+ * Exponent forms are deliberately rejected. Every field parsed by this function sizes the
+ * file geometry, and `'1E3'` in one of them is far likelier to be corruption than a writer's
+ * idea of 1000 — accepting it would turn unreadable bytes into a confidently wrong offset.
+ * `'256.0'` is rejected for the same reason.
+ */
+export function parseEdfInteger(raw) {
+    return parseField(raw, INTEGER_GRAMMAR, true);
+}
+/**
+ * Parse a field that may be fractional: physical minimum and maximum, record duration.
+ *
+ * Accepts a leading sign, a bare leading or trailing point, and an exponent, because writers
+ * in the wild emit `'+22'`, `'.5'`, `'1E3'` and `'-1.23E-4'`.
+ */
+export function parseEdfNumber(raw) {
+    return parseField(raw, NUMBER_GRAMMAR, false);
+}
+//# sourceMappingURL=numbers.js.map

package/dist/bytes/numbers.js.map

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

package/dist/bytes/view.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.)
+ */
+/**
+ * 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 declare function sliceBytes(bytes: Uint8Array, offset: number, length: number): Uint8Array;
+/** `length` bytes at `offset`, copied into a buffer of their own. */
+export declare function copyBytes(bytes: Uint8Array, offset: number, length: number): Uint8Array;
+/**
+ * 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 declare function readAsciiField(bytes: Uint8Array, offset: number, length: number): string;
+//# sourceMappingURL=view.d.ts.map

package/dist/bytes/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/bytes/view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwBH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAGxF;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAGvF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExF"}