edfcore 0.1.0

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "edfcore",
+  "version": "0.1.0",
+  "description": "Modern, typed, zero-dependency reader for EDF, EDF+, BDF and BDF+ biosignal files. Works in browsers and Node with true random access.",
+  "keywords": [
+    "edf",
+    "edf+",
+    "bdf",
+    "bdf+",
+    "eeg",
+    "ecg",
+    "emg",
+    "polysomnography",
+    "sleep",
+    "biosignal",
+    "european-data-format",
+    "neuroscience",
+    "neurotech",
+    "parser",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Sarthak Tayal",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tayal-sarthak/edfcore.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tayal-sarthak/edfcore/issues"
+  },
+  "homepage": "https://edfcore.vercel.app",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "default": "./dist/validate.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.6",
+    "@types/node": "^26.1.2",
+    "fast-check": "4.9.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "corpus:fetch": "node scripts/fetch-corpus.mjs",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bytes/latin1.ts

@@ -0,0 +1,87 @@
+/**
+ * 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: Uint8Array): string {
+  // 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 as unknown as number[]);
+}
+
+/**
+ * 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: Uint8Array): string {
+  if (bytes.length <= CHUNK_BYTES) return fromCharCodes(bytes);
+  const parts: string[] = [];
+  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: Uint8Array): boolean {
+  for (const byte of bytes) {
+    if (byte < PRINTABLE_ASCII_MIN || byte > PRINTABLE_ASCII_MAX) return true;
+  }
+  return false;
+}
+
+function isPadding(code: number): boolean {
+  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: string): string {
+  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);
+}

package/src/bytes/numbers.ts

@@ -0,0 +1,115 @@
+/**
+ * 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';
+}
+
+type EdfNumberProblem = EdfNumberParse['problem'];
+
+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: number): boolean {
+  return code === CHAR_SPACE || code === CHAR_NUL;
+}
+
+function failure(raw: string, problem: EdfNumberProblem): EdfNumberParse {
+  return { ok: false, value: Number.NaN, raw, problem };
+}
+
+function containsNul(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) === CHAR_NUL) return true;
+  }
+  return false;
+}
+
+function parseField(raw: string, grammar: RegExp, integral: boolean): EdfNumberParse {
+  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: string): EdfNumberParse {
+  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: string): EdfNumberParse {
+  return parseField(raw, NUMBER_GRAMMAR, false);
+}

package/src/bytes/view.ts

@@ -0,0 +1,59 @@
+/**
+ * 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: Uint8Array, offset: number, length: number): void {
+  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: Uint8Array, offset: number, length: number): Uint8Array {
+  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: Uint8Array, offset: number, length: number): Uint8Array {
+  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: Uint8Array, offset: number, length: number): string {
+  return decodeHeaderLatin1(sliceBytes(bytes, offset, length));
+}

package/src/constants.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 as const;
+
+/** Total header size is always `EDF_HEADER_BLOCK_BYTES * (signalCount + 1)`. */
+export const EDF_SIGNAL_HEADER_BYTES = 256 as const;
+
+/** Trimmed, case-sensitive. On disk the field is `'EDF Annotations '` — 15 chars plus a pad. */
+export const EDF_ANNOTATIONS_LABEL = 'EDF Annotations' as const;
+export const BDF_ANNOTATIONS_LABEL = 'BDF Annotations' as const;
+
+/** EDF spec recommendation, not a limit. Exceeding it is a warning, never an error. */
+export const EDF_RECOMMENDED_MAX_RECORD_BYTES = 61440 as const;
+
+/**
+ * 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 as const;
+export const EDF_DIGITAL_MAX = 32767 as const;
+
+/** 24-bit two's complement, sign-extended from bit 23. */
+export const BDF_DIGITAL_MIN = -8388608 as const;
+export const BDF_DIGITAL_MAX = 8388607 as const;
+
+/** ns lives in a 4-byte field, so it cannot exceed four digits. */
+export const EDF_MAX_SIGNAL_COUNT = 9999 as const;
+
+/** Default ceiling for any read that allocates. Refused before allocating, not during. */
+export const DEFAULT_MAX_MATERIALIZE_BYTES: number = 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 as const;
+export const TAL_FIELD_TERMINATOR = 0x14 as const;
+export const TAL_TERMINATOR = 0x00 as const;
+
+/** 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 },
+} as const;
+
+/**
+ * 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,
+} as const;
+
+/** 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,
+} as const;
+
+/** Published package version. Kept in sync with package.json by a test. */
+export const VERSION = '0.1.0';