edfcore 0.5.61 → 0.5.63

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.5.61";
+export declare const VERSION = "0.5.63";
 //# 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.5.61';
+export const VERSION = '0.5.63';
 //# 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;AAGH,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAoC3D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAoCtE"}
+{"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;AAsD3D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAkDtE"}

package/dist/io/bytes.js

@@ -43,6 +43,24 @@ function describe(value) {
  * reason and this one was missed.
  */
 const BUFFER_TAGS = new Set(['[object ArrayBuffer]', '[object SharedArrayBuffer]']);
+/**
+ * Whether a buffer's bytes have been transferred away — `postMessage(bytes, [bytes.buffer])`, or
+ * `ArrayBuffer.prototype.transfer()`. A view over one keeps its tag and reports a `byteLength` of
+ * 0, so nothing else here can tell it apart from an empty array.
+ *
+ * `slice` rather than `ArrayBuffer.prototype.detached`, which says this in one word and arrives in
+ * ES2024 — above the ES2022 floor `browser-floor.test.ts` pins. A `SharedArrayBuffer` never
+ * detaches and answers false.
+ */
+function isDetachedBuffer(buffer) {
+    try {
+        buffer.slice(0, 0);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * A `ByteSource` over bytes already in memory, for a file you fetched yourself or a fixture in a
  * test. The signedness of the view is checked at construction rather than at first read: an
@@ -65,6 +83,16 @@ export function byteSource(bytes) {
             '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 });
     }
+    // Refused at construction for the same reason, and it is the case the worker story produces:
+    // transferring bytes to a worker detaches the sender's buffer, and a view over it is still a
+    // Uint8Array with the right tag and a byteLength of 0. Building a source over that reports
+    // `[SOURCE_TOO_SMALL] the header is 0 bytes` — blaming the FILE for an argument the caller no
+    // longer owns.
+    if (isDetachedBuffer(isByteArray(bytes) ? bytes.buffer : bytes)) {
+        throw new EdfSourceError('byteSource() received a detached ArrayBuffer: its bytes were transferred to another ' +
+            'realm, so this one holds none of them. Next: read the file on the side that owns the ' +
+            'bytes now, or post them without a transfer list so both sides keep a copy.', { 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);

package/dist/io/bytes.js.map

@@ -1 +1 @@
-{"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;;;;;;;;;;GAUG;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;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,sBAAsB,EAAE,4BAA4B,CAAC,CAAC,CAAC;AAEpF;;;;GAIG;AACH,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,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,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"}
+{"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;;;;;;;;;;GAUG;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;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,sBAAsB,EAAE,4BAA4B,CAAC,CAAC,CAAC;AAEpF;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,MAAuB;IAC/C,IAAI,CAAC;QACH,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,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,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,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,6FAA6F;IAC7F,6FAA6F;IAC7F,2FAA2F;IAC3F,8FAA8F;IAC9F,eAAe;IACf,IAAI,gBAAgB,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,KAAqB,CAAC,EAAE,CAAC;QACjF,MAAM,IAAI,cAAc,CACtB,sFAAsF;YACpF,uFAAuF;YACvF,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/docs/CHANGELOG.md

@@ -6,6 +6,49 @@ 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.5.63
+
+- **Added** the other half of the zero-copy bargain. `byteSource` is documented as handing out
+  `subarray` views over the caller's own buffer, and `io/bytes.ts` argues that is safe because the
+  adapter retains nothing the caller does not already hold. That is a claim about the ADAPTER. The
+  values the reading API builds out of those views are what a caller keeps, and nothing said
+  whether any of them still points at the buffer.
+- Two sites state the rule for themselves and neither was checked: `header/parse.ts` copies the
+  header bytes so "a header that quietly changed under a hexdump" cannot happen, and
+  `diagnostics/collector.ts` copies a diagnostic's evidence because "a diagnostic outlives the read
+  that produced it".
+- The second is the one holding it up. `readHeader` joins its two reads into a buffer of its own,
+  so the header is copied twice over and the `copyBytes` there is belt on braces. The four
+  `rawBytes` in `tal/` are `sliceBytes` — a `subarray` of the record bytes — and `readRecordBytes`
+  returns those straight from the source. Removing the collector's `.slice()` makes a
+  `TAL_MALFORMED` diagnostic hand back a window into the caller's file, and this file fails.
+- `nothing-points-at-your-buffer.test.ts` walks every value every entry point returns over all ten
+  `AWKWARD` shapes, a gapped file and one whose TAL onsets are not numbers, and requires every
+  typed array to be backed by some other buffer. Then it overwrites the caller's bytes end to end
+  and compares each answer against a `structuredClone` taken before — the failure a caller would
+  actually meet, having reused the array they fetched into.
+- Two assertions keep it honest: that a `byteSource` read really does alias, so the risk is real,
+  and that the sweep reached a diagnostic quoting record bytes rather than only the header, so a
+  pass is not a pass on the one path that was never in question.
+
+## 0.5.62
+
+- **Fixed** `byteSource` accepting a detached `ArrayBuffer` and building a zero-byte source over
+  it. `openEdf` then reported `[SOURCE_TOO_SMALL] the header is 0 bytes` — blaming the FILE for an
+  argument the caller no longer owns, which is the one confusion this constructor's own comment
+  says it exists to avoid. It refuses at construction now, with a message naming the transfer.
+- A detached view is not an exotic input: `postMessage(bytes, [bytes.buffer])` is the ordinary way
+  to hand a recording to a worker, and it detaches the SENDER's buffer. A worker page that posts
+  the bytes and then opens them locally, or that transfers by mistake where it meant to copy, gets
+  a diagnostic about a file that is fine.
+- Nothing else about the guard moves. A view over a detached buffer keeps its `Uint8Array` tag and
+  reports a `byteLength` of 0, so neither the tag test nor a length check can tell it from an empty
+  array — and a genuinely empty `Uint8Array` is still accepted and still reaches `SOURCE_TOO_SMALL`,
+  which for zero bytes you actually hold is the truthful answer. A `SharedArrayBuffer` never
+  detaches and is unaffected.
+- The check is `buffer.slice(0, 0)` rather than `ArrayBuffer.prototype.detached`, which says it in
+  one word and arrives in ES2024 — above the ES2022 floor `browser-floor.test.ts` pins.
+
 ## 0.5.61
 
 - **Fixed** a sentence both `api-errors.md` and `diagnostics.md` end their cross-realm advice with,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.5.61",
+  "version": "0.5.63",
   "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.5.61';
+export const VERSION = '0.5.63';

package/src/io/bytes.ts

@@ -44,6 +44,24 @@ function describe(value: unknown): string {
  */
 const BUFFER_TAGS = new Set(['[object ArrayBuffer]', '[object SharedArrayBuffer]']);
 
+/**
+ * Whether a buffer's bytes have been transferred away — `postMessage(bytes, [bytes.buffer])`, or
+ * `ArrayBuffer.prototype.transfer()`. A view over one keeps its tag and reports a `byteLength` of
+ * 0, so nothing else here can tell it apart from an empty array.
+ *
+ * `slice` rather than `ArrayBuffer.prototype.detached`, which says this in one word and arrives in
+ * ES2024 — above the ES2022 floor `browser-floor.test.ts` pins. A `SharedArrayBuffer` never
+ * detaches and answers false.
+ */
+function isDetachedBuffer(buffer: ArrayBufferLike): boolean {
+  try {
+    buffer.slice(0, 0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
 /**
  * A `ByteSource` over bytes already in memory, for a file you fetched yourself or a fixture in a
  * test. The signedness of the view is checked at construction rather than at first read: an
@@ -70,6 +88,20 @@ export function byteSource(bytes: ArrayBuffer | Uint8Array): ByteSource {
     );
   }
 
+  // Refused at construction for the same reason, and it is the case the worker story produces:
+  // transferring bytes to a worker detaches the sender's buffer, and a view over it is still a
+  // Uint8Array with the right tag and a byteLength of 0. Building a source over that reports
+  // `[SOURCE_TOO_SMALL] the header is 0 bytes` — blaming the FILE for an argument the caller no
+  // longer owns.
+  if (isDetachedBuffer(isByteArray(bytes) ? bytes.buffer : (bytes as ArrayBuffer))) {
+    throw new EdfSourceError(
+      'byteSource() received a detached ArrayBuffer: its bytes were transferred to another ' +
+        'realm, so this one holds none of them. Next: read the file on the side that owns the ' +
+        'bytes now, or post them without a transfer list so both sides keep a copy.',
+      { 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);