edfcore 0.2.33 → 0.2.35

package/CHANGELOG.md

@@ -6,6 +6,38 @@ alone does not tell you whether you were affected.
 edfcore is pre-1.0. Patch releases have carried behaviour changes where the old behaviour was a
 defect; those are called out below.
 
+## 0.2.35
+
+- **Fixed** `byteSource` building a source over an argument that is not bytes, so the caller's
+  mistake was reported as a defect in the file. `new Uint8Array(x)` accepts almost anything: a
+  string, a plain object and `null` all yield an empty array, and a `number[]` yields one of the
+  wrong length. The source was constructed happily and the failure surfaced later as
+  `[SOURCE_TOO_SMALL] the header is 0 bytes` — the file blamed for the argument, which is the one
+  confusion this package works hardest to avoid. It now refuses at construction and says what it
+  wanted. `Int8Array` is refused by name: one byte per element, so it passes every length check
+  and then decodes to fabricated sample values.
+
+## 0.2.34
+
+- **Added** the golden-value harness this README has withheld a numerical-interop claim for since
+  0.1.0. edfcore now **reproduces pyEDFlib's float64 physical values bit for bit** on EDF and
+  24-bit BDF, across symmetric and asymmetric declared ranges. `scripts/golden/generate.py` writes
+  the fixtures with pyEDFlib's own writer, reads them back with pyEDFlib, and records every sample
+  as its exact IEEE-754 bit pattern; the test compares with `Object.is`, so one ULP is a failure.
+  Nothing under `tests/corpus/golden/` was produced by edfcore, and the goldens are committed so
+  CI never needs Python.
+
+  Every previous test of the pinned scaling expression re-derived that same expression inside the
+  test, which proved edfcore agrees with itself and nothing more. This is the first evidence that
+  the choice to keep EDFlib's numerically worse form was worth making: substituting the textbook
+  `physicalMinimum + (digital - digitalMinimum) * gain` fails on 140 of 256 samples of the
+  symmetric fixture — `-492.15686274509807` where pyEDFlib says `-492.156862745098` — and a test
+  asserts that the goldens can tell the two apart, so the parity is a real constraint rather than
+  a coincidence of the fixtures.
+
+  Still not claimed, because no test produces it yet: parity with MNE, and validation across the
+  public corpora.
+
 ## 0.2.33
 
 - **Fixed** annotations being dropped with no diagnostic naming them. `TIMEKEEPING_TAL_NONCONFORMANT`

package/README.md

@@ -291,10 +291,17 @@ the reason to trust the reader.
 **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.
+**Numerical interop, as of 0.2.34.** edfcore reproduces **pyEDFlib's float64 physical values bit
+for bit** on EDF and 24-bit BDF, across symmetric and asymmetric ranges. That is a test, not a
+belief: `scripts/golden/generate.py` writes the fixtures with pyEDFlib's own writer, reads them
+back with pyEDFlib, and records every sample as its exact IEEE-754 bit pattern;
+`tests/corpus/golden-values.test.ts` compares with `Object.is`, so one ULP is a failure. Nothing in
+`tests/corpus/golden/` was produced by edfcore. Substituting the numerically better textbook
+expression fails it on 140 of 256 samples — which is why the EDFlib form is pinned.
+
+**Still open before 1.0.** The same harness against MNE, and validation across public corpora
+(sleep-edfx, CHB-MIT, the BioSemi and edfplus.info test files). Those claims are not made here
+until a test produces them.
 
 **Shipped since 0.1.6.** Min/max envelope decimation (`readEnvelope`,
 `readEnvelopeAtResolution`). BioSemi Status-byte helpers (`readTriggers`). Streaming iteration

package/dist/constants.d.ts

@@ -109,5 +109,5 @@ export declare const SIGNAL_FIELD_BLOCK_OFFSETS: {
     readonly reserved: 224;
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export declare const VERSION = "0.2.33";
+export declare const VERSION = "0.2.35";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -79,5 +79,5 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
     reserved: 224,
 };
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.2.33';
+export const VERSION = '0.2.35';
 //# sourceMappingURL=constants.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/io/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAG3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAgBtE"}
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/io/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAe3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAsCtE"}

package/dist/io/bytes.js

@@ -6,11 +6,44 @@
  * owned by the caller" rule exists to stop an adapter handing out a view into state it retains,
  * and this adapter retains nothing the caller does not already hold.
  */
-import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+import { EdfSourceError } from '../errors.js';
+import { assertExactRead, assertReadRange, isByteArray, throwIfAborted } from './source.js';
+/**
+ * Describes what arrived, for an argument that is not bytes. Never prints the value: it could be
+ * anything, including something large.
+ */
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (ArrayBuffer.isView(value))
+        return Object.prototype.toString.call(value).slice(8, -1);
+    if (Array.isArray(value))
+        return 'a plain Array';
+    return typeof value === 'object' ? 'a plain object' : `a ${typeof value}`;
+}
 export function byteSource(bytes) {
-    // `ArrayBuffer.isView` rather than `instanceof Uint8Array`: `instanceof` is false for a view
-    // that crossed a realm boundary (a worker, an iframe), and this is a public entry point.
-    const view = ArrayBuffer.isView(bytes) ? bytes : new Uint8Array(bytes);
+    // Refused at CONSTRUCTION, because the alternative is worse than an error. `new Uint8Array(x)`
+    // accepts almost anything: a string, a plain object and `null` all yield an empty array, and a
+    // `number[]` yields one of the wrong length. The source was then built happily and the failure
+    // surfaced later as `[SOURCE_TOO_SMALL] the header is 0 bytes` — blaming the FILE for a mistake
+    // in the caller's argument, which is the one confusion this package works hardest to avoid.
+    //
+    // `Int8Array` is rejected too, and deliberately: it has one byte per element so it passes any
+    // length check, and its already-signed elements are sign-extended a second time during decode
+    // (see `assertExactRead`). Fabricated microvolts, with no error anywhere.
+    const isBuffer = bytes instanceof ArrayBuffer ||
+        Object.prototype.toString.call(bytes) === '[object SharedArrayBuffer]';
+    if (!isBuffer && !isByteArray(bytes)) {
+        throw new EdfSourceError(`byteSource() needs an ArrayBuffer or a Uint8Array, received ${describe(bytes)}. ` +
+            'Next: pass `new Uint8Array(await blob.arrayBuffer())`, `await readFile(path)`, or the ' +
+            'ArrayBuffer itself. An Int8Array is not accepted — it has one byte per element, so it ' +
+            'would pass every length check and then decode to fabricated sample values.', { offset: 0, requestedLength: 0 });
+    }
+    // `isByteArray` rather than `instanceof Uint8Array`: `instanceof` is false for a view that
+    // crossed a realm boundary (a worker, an iframe), and this is a public entry point.
+    const view = isByteArray(bytes) ? bytes : new Uint8Array(bytes);
     const byteLength = view.byteLength;
     return {
         byteLength,

package/dist/io/bytes.js.map

@@ -1 +1 @@
-{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/io/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/E,MAAM,UAAU,UAAU,CAAC,KAA+B;IACxD,6FAA6F;IAC7F,yFAAyF;IACzF,MAAM,IAAI,GAAe,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACnF,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAEnC,OAAO;QACL,UAAU;QACV,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,MAAc,EAAE,OAAqB;YAC9D,cAAc,CAAC,OAAO,CAAC,CAAC;YACxB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YAC5C,iFAAiF;YACjF,+EAA+E;YAC/E,OAAO,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACjF,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/io/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5F;;;GAGG;AACH,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC5C,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACzF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,eAAe,CAAC;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,KAAK,EAAE,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAA+B;IACxD,+FAA+F;IAC/F,+FAA+F;IAC/F,+FAA+F;IAC/F,gGAAgG;IAChG,4FAA4F;IAC5F,EAAE;IACF,8FAA8F;IAC9F,8FAA8F;IAC9F,0EAA0E;IAC1E,MAAM,QAAQ,GACZ,KAAK,YAAY,WAAW;QAC5B,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,4BAA4B,CAAC;IACzE,IAAI,CAAC,QAAQ,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,cAAc,CACtB,+DAA+D,QAAQ,CAAC,KAAK,CAAC,IAAI;YAChF,wFAAwF;YACxF,wFAAwF;YACxF,4EAA4E,EAC9E,EAAE,MAAM,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,CAClC,CAAC;IACJ,CAAC;IAED,2FAA2F;IAC3F,oFAAoF;IACpF,MAAM,IAAI,GAAe,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAoB,CAAC,CAAC;IAC3F,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAEnC,OAAO;QACL,UAAU;QACV,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,MAAc,EAAE,OAAqB;YAC9D,cAAc,CAAC,OAAO,CAAC,CAAC;YACxB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YAC5C,iFAAiF;YACjF,+EAA+E;YAC/E,OAAO,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACjF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/io/source.d.ts

@@ -11,6 +11,14 @@
  * cause for the wrong thing.
  */
 import type { AbortSignalLike, ReadOptions } from '../types.js';
+/**
+ * Whether a value is a real one-byte-per-element view: `Uint8Array`, `Uint8ClampedArray`, or
+ * Node's `Buffer` (a `Uint8Array` subclass, so it inherits the tag).
+ *
+ * Shared with `byteSource`, which has to reject the same set at construction time rather than
+ * building a source over something that is not bytes.
+ */
+export declare function isByteArray(value: unknown): value is Uint8Array;
 /**
  * Enforces the exact-length contract and returns the value unchanged so it can wrap a read
  * expression directly.

package/dist/io/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/io/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAgChE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAYhG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAuBxF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAKnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/io/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA0BhE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAE/D;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAYhG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAuBxF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAKnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,MAAM,CAQR"}

package/dist/io/source.js

@@ -34,12 +34,18 @@ import { EdfSourceError } from '../errors.js';
  * tag — and `Uint8ClampedArray`, and rejects `Int8Array`, every wider view, and `DataView`.
  */
 const BYTE_ARRAY_TAGS = new Set(['[object Uint8Array]', '[object Uint8ClampedArray]']);
+/**
+ * Whether a value is a real one-byte-per-element view: `Uint8Array`, `Uint8ClampedArray`, or
+ * Node's `Buffer` (a `Uint8Array` subclass, so it inherits the tag).
+ *
+ * Shared with `byteSource`, which has to reject the same set at construction time rather than
+ * building a source over something that is not bytes.
+ */
+export function isByteArray(value) {
+    return ArrayBuffer.isView(value) && BYTE_ARRAY_TAGS.has(Object.prototype.toString.call(value));
+}
 function receivedLengthOf(received) {
-    if (!ArrayBuffer.isView(received))
-        return undefined;
-    if (!BYTE_ARRAY_TAGS.has(Object.prototype.toString.call(received)))
-        return undefined;
-    return received.byteLength;
+    return isByteArray(received) ? received.byteLength : undefined;
 }
 /**
  * Enforces the exact-length contract and returns the value unchanged so it can wrap a read

package/dist/io/source.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "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",

package/src/constants.ts

@@ -93,4 +93,4 @@ export const SIGNAL_FIELD_BLOCK_OFFSETS = {
 } as const;
 
 /** Published package version. Kept in sync with package.json by a test. */
-export const VERSION = '0.2.33';
+export const VERSION = '0.2.35';

package/src/io/bytes.ts

@@ -7,13 +7,48 @@
  * and this adapter retains nothing the caller does not already hold.
  */
 
+import { EdfSourceError } from '../errors.js';
 import type { ByteSource, ReadOptions } from '../types.js';
-import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+import { assertExactRead, assertReadRange, isByteArray, throwIfAborted } from './source.js';
+
+/**
+ * Describes what arrived, for an argument that is not bytes. Never prints the value: it could be
+ * anything, including something large.
+ */
+function describe(value: unknown): string {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  if (ArrayBuffer.isView(value)) return Object.prototype.toString.call(value).slice(8, -1);
+  if (Array.isArray(value)) return 'a plain Array';
+  return typeof value === 'object' ? 'a plain object' : `a ${typeof value}`;
+}
 
 export function byteSource(bytes: ArrayBuffer | Uint8Array): ByteSource {
-  // `ArrayBuffer.isView` rather than `instanceof Uint8Array`: `instanceof` is false for a view
-  // that crossed a realm boundary (a worker, an iframe), and this is a public entry point.
-  const view: Uint8Array = ArrayBuffer.isView(bytes) ? bytes : new Uint8Array(bytes);
+  // Refused at CONSTRUCTION, because the alternative is worse than an error. `new Uint8Array(x)`
+  // accepts almost anything: a string, a plain object and `null` all yield an empty array, and a
+  // `number[]` yields one of the wrong length. The source was then built happily and the failure
+  // surfaced later as `[SOURCE_TOO_SMALL] the header is 0 bytes` — blaming the FILE for a mistake
+  // in the caller's argument, which is the one confusion this package works hardest to avoid.
+  //
+  // `Int8Array` is rejected too, and deliberately: it has one byte per element so it passes any
+  // length check, and its already-signed elements are sign-extended a second time during decode
+  // (see `assertExactRead`). Fabricated microvolts, with no error anywhere.
+  const isBuffer =
+    bytes instanceof ArrayBuffer ||
+    Object.prototype.toString.call(bytes) === '[object SharedArrayBuffer]';
+  if (!isBuffer && !isByteArray(bytes)) {
+    throw new EdfSourceError(
+      `byteSource() needs an ArrayBuffer or a Uint8Array, received ${describe(bytes)}. ` +
+        'Next: pass `new Uint8Array(await blob.arrayBuffer())`, `await readFile(path)`, or the ' +
+        'ArrayBuffer itself. An Int8Array is not accepted — it has one byte per element, so it ' +
+        'would pass every length check and then decode to fabricated sample values.',
+      { offset: 0, requestedLength: 0 },
+    );
+  }
+
+  // `isByteArray` rather than `instanceof Uint8Array`: `instanceof` is false for a view that
+  // crossed a realm boundary (a worker, an iframe), and this is a public entry point.
+  const view: Uint8Array = isByteArray(bytes) ? bytes : new Uint8Array(bytes as ArrayBuffer);
   const byteLength = view.byteLength;
 
   return {

package/src/io/source.ts

@@ -38,10 +38,19 @@ import type { AbortSignalLike, ReadOptions } from '../types.js';
  */
 const BYTE_ARRAY_TAGS = new Set(['[object Uint8Array]', '[object Uint8ClampedArray]']);
 
+/**
+ * Whether a value is a real one-byte-per-element view: `Uint8Array`, `Uint8ClampedArray`, or
+ * Node's `Buffer` (a `Uint8Array` subclass, so it inherits the tag).
+ *
+ * Shared with `byteSource`, which has to reject the same set at construction time rather than
+ * building a source over something that is not bytes.
+ */
+export function isByteArray(value: unknown): value is Uint8Array {
+  return ArrayBuffer.isView(value) && BYTE_ARRAY_TAGS.has(Object.prototype.toString.call(value));
+}
+
 function receivedLengthOf(received: unknown): number | undefined {
-  if (!ArrayBuffer.isView(received)) return undefined;
-  if (!BYTE_ARRAY_TAGS.has(Object.prototype.toString.call(received))) return undefined;
-  return received.byteLength;
+  return isByteArray(received) ? received.byteLength : undefined;
 }
 
 /**