edfcore 0.6.184 → 0.6.185

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.6.184";
+export declare const VERSION = "0.6.185";
 //# 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.6.184';
+export const VERSION = '0.6.185';
 //# sourceMappingURL=constants.js.map

package/dist/format-annotations.d.ts

@@ -26,14 +26,5 @@ export interface FormatAnnotationsOptions {
     /** Include the `description@@channel` label EDF+ allows. Off by default: most files have none. */
     readonly includeChannel?: boolean;
 }
-/**
- * A multi-line listing, one annotation per line, in the order given.
- *
- * Returns `''` for an empty list rather than a blank line, so it concatenates into a larger
- * report cleanly — the same rule `formatDiagnostics` follows.
- *
- * The order is the caller's. `readAnnotations` already returns them sorted by onset, and
- * re-sorting here would quietly discard a deliberate `filterAnnotationsByText` ordering.
- */
 export declare function formatAnnotations(annotations: readonly EdfAnnotation[], options?: FormatAnnotationsOptions): string;
 //# sourceMappingURL=format-annotations.d.ts.map

package/dist/format-annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format-annotations.d.ts","sourceRoot":"","sources":["../src/format-annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA0CD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,CAsER"}
+{"version":3,"file":"format-annotations.d.ts","sourceRoot":"","sources":["../src/format-annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA4ED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,CAuER"}

package/dist/format-annotations.js

@@ -62,6 +62,29 @@ function duration(annotation) {
  * The order is the caller's. `readAnnotations` already returns them sorted by onset, and
  * re-sorting here would quietly discard a deliberate `filterAnnotationsByText` ordering.
  */
+/**
+ * The ELEMENTS, which the array check below never reaches.
+ *
+ * `formatDiagnostics` grew this in 0.6.160 and `summarizeDiagnostics` in 0.6.168, on the same
+ * argument: an array of the wrong thing satisfies `Array.isArray` and is then read for fields it
+ * does not have. The first field read here is `onsetTicksFromFirstRecord`, a BigInt, so a list of
+ * anything else threw V8's `Cannot mix BigInt and other types, use explicit conversions` — a
+ * sentence about arithmetic, out of a printer, naming no argument and carrying no `Next:` clause.
+ *
+ * `header.diagnostics` is the list that gets passed. It is the other array a reader holds after
+ * opening a file, `formatDiagnostics` sits beside this call in the barrel, and the two take the same
+ * shape of argument with the same shape of options — so the pair is easy to cross.
+ */
+function assertAnnotation(annotation, index) {
+    const onset = annotation
+        ?.onsetTicksFromFirstRecord;
+    if (typeof onset === 'bigint')
+        return;
+    throw new RangeError(`formatAnnotations(): the value at ${index} carries no onset, so it is not an annotation — ` +
+        'this listing is one row per event, timed from the start of record 0. Next: pass the ' +
+        '`annotations` field of what readAnnotations(recording, records) resolved to, or print a ' +
+        'list of diagnostics with formatDiagnostics().');
+}
 export function formatAnnotations(annotations, options) {
     /*
      * `''` is this function's "no events", which is what makes a wrong argument dangerous here rather
@@ -99,6 +122,7 @@ export function formatAnnotations(annotations, options) {
         const annotation = annotations[i];
         if (annotation === undefined)
             continue;
+        assertAnnotation(annotation, i);
         cells.push({
             onset: clock(annotation.onsetTicksFromFirstRecord),
             duration: duration(annotation),

package/dist/format-annotations.js.map

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

package/docs/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.6.185
+
+- **Fixed** `formatAnnotations` dying on the onset arithmetic for an array of the wrong thing. The
+  guard 0.6.95 added tests `Array.isArray`, and an array of anything passes it; the first field this
+  listing reads is `onsetTicksFromFirstRecord`, a BigInt, so the answer was V8's `Cannot mix BigInt
+  and other types, use explicit conversions` — a sentence about arithmetic, out of a printer, naming
+  no argument and carrying no `Next:` clause.
+- `header.diagnostics` is the list that gets passed: the other array a reader holds after opening a
+  file, printed by the call that sits beside this one in the barrel, taking the same shape of
+  argument with the same shape of options.
+- `formatDiagnostics` closed this in 0.6.160 and `summarizeDiagnostics` in 0.6.168, each checking the
+  one field its own rows must carry. This is the third of the three, and it checks the onset.
+
 ## 0.6.184
 
 - **Fixed** `httpSource` handing an unusable address to `fetch` and letting `fetch` answer for it.

package/package.json

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

package/src/format-annotations.ts

@@ -83,6 +83,31 @@ function duration(annotation: EdfAnnotation): string {
  * The order is the caller's. `readAnnotations` already returns them sorted by onset, and
  * re-sorting here would quietly discard a deliberate `filterAnnotationsByText` ordering.
  */
+/**
+ * The ELEMENTS, which the array check below never reaches.
+ *
+ * `formatDiagnostics` grew this in 0.6.160 and `summarizeDiagnostics` in 0.6.168, on the same
+ * argument: an array of the wrong thing satisfies `Array.isArray` and is then read for fields it
+ * does not have. The first field read here is `onsetTicksFromFirstRecord`, a BigInt, so a list of
+ * anything else threw V8's `Cannot mix BigInt and other types, use explicit conversions` — a
+ * sentence about arithmetic, out of a printer, naming no argument and carrying no `Next:` clause.
+ *
+ * `header.diagnostics` is the list that gets passed. It is the other array a reader holds after
+ * opening a file, `formatDiagnostics` sits beside this call in the barrel, and the two take the same
+ * shape of argument with the same shape of options — so the pair is easy to cross.
+ */
+function assertAnnotation(annotation: EdfAnnotation, index: number): void {
+  const onset = (annotation as { onsetTicksFromFirstRecord?: unknown } | null | undefined)
+    ?.onsetTicksFromFirstRecord;
+  if (typeof onset === 'bigint') return;
+  throw new RangeError(
+    `formatAnnotations(): the value at ${index} carries no onset, so it is not an annotation — ` +
+      'this listing is one row per event, timed from the start of record 0. Next: pass the ' +
+      '`annotations` field of what readAnnotations(recording, records) resolved to, or print a ' +
+      'list of diagnostics with formatDiagnostics().',
+  );
+}
+
 export function formatAnnotations(
   annotations: readonly EdfAnnotation[],
   options?: FormatAnnotationsOptions,
@@ -125,6 +150,7 @@ export function formatAnnotations(
   for (let i = 0; i < limit; i += 1) {
     const annotation = annotations[i];
     if (annotation === undefined) continue;
+    assertAnnotation(annotation, i);
     cells.push({
       onset: clock(annotation.onsetTicksFromFirstRecord),
       duration: duration(annotation),