edfcore 0.2.61 → 0.2.63

package/CHANGELOG.md

@@ -6,6 +6,34 @@ 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.62
+
+- **Added** `formatAnnotations`, the third formatter beside `formatHeader` and
+  `formatDiagnostics`, and the one a hypnogram or an event list actually needs.
+- The clock is built from `onsetTicksFromFirstRecord` by integer division, never from the float
+  seconds. An event list is exactly where someone reads a number off the screen and types it into
+  something else, and a millisecond field derived from a float64 that came out of a division by
+  10,000,000 can be off by one. A test makes the two fields disagree deliberately, so only a
+  formatter reading the exact one passes.
+- Hours are not wrapped at 24 — a 30-hour recording is real, and `30:12` is more useful than
+  `06:12` on day two. Times truncate to the millisecond rather than rounding, so the printed
+  instant is never later than the event. A NEGATIVE onset prints as one: EDF+ measures onsets from
+  the header start time, a recording may begin after its first annotation, and clamping to zero
+  would silently move it.
+
+## 0.2.61
+
+- **Deprecated** `sampleIndexAt`, `sampleStartTicks` and `sampleStartSeconds`, which are renamed
+  to `gridSampleIndexAt`, `gridSampleStartTicks` and `gridSampleStartSeconds` in **0.3.0**. The
+  behaviour does not change and neither do the arguments — only the name, which never said which of
+  two different quantities it returns. Six releases of this project were spent on exactly that
+  confusion elsewhere, and the `grid` prefix is what stops the seventh.
+- The tag is folded into each function's existing documentation rather than added as a second
+  comment above it, so an editor shows the original prose AND the replacement instead of replacing
+  one with the other.
+- Nothing is removed here. An editor will point at the replacement a release before the rename
+  lands, and for a contiguous file the rename is the only thing that affects a caller.
+
 ## 0.2.60
 
 - **Added** `sampleAt`, `sampleStartTicksOf` and `sampleStartSecondsOf` — the recording-aware

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

package/dist/format-annotations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Annotations as text.
+ *
+ * Layer 7, and pure. `formatHeader` does this for the header and `formatDiagnostics` for problems;
+ * this is the third, and the one a hypnogram or an event list actually needs.
+ *
+ * The clock is built from `onsetTicksFromFirstRecord` by integer division, never from the float
+ * seconds. That is not fussiness: `onsetSecondsFromFirstRecord` is a float64 produced by dividing
+ * an exact tick count by 10,000,000, so an onset written `+1.0000001` can print a millisecond
+ * field that is off by one — and an event list is exactly where someone reads a number off the
+ * screen and types it into something else.
+ *
+ * A NEGATIVE onset is legal and prints as one. EDF+ measures onsets from the header start time
+ * and a recording may begin after its first annotation, so `-00:00:01.500` is a real thing a real
+ * file says. Clamping it to zero would silently move an event.
+ */
+import type { EdfAnnotation } from './types.js';
+export interface FormatAnnotationsOptions {
+    /** Rows to print. Defaults to every annotation; the count of the rest is always stated. */
+    readonly maxItems?: number;
+    /** 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

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

package/dist/format-annotations.js

@@ -0,0 +1,83 @@
+/**
+ * Annotations as text.
+ *
+ * Layer 7, and pure. `formatHeader` does this for the header and `formatDiagnostics` for problems;
+ * this is the third, and the one a hypnogram or an event list actually needs.
+ *
+ * The clock is built from `onsetTicksFromFirstRecord` by integer division, never from the float
+ * seconds. That is not fussiness: `onsetSecondsFromFirstRecord` is a float64 produced by dividing
+ * an exact tick count by 10,000,000, so an onset written `+1.0000001` can print a millisecond
+ * field that is off by one — and an event list is exactly where someone reads a number off the
+ * screen and types it into something else.
+ *
+ * A NEGATIVE onset is legal and prints as one. EDF+ measures onsets from the header start time
+ * and a recording may begin after its first annotation, so `-00:00:01.500` is a real thing a real
+ * file says. Clamping it to zero would silently move an event.
+ */
+import { TICKS_PER_SECOND } from './constants.js';
+const TICKS_PER_MILLISECOND = TICKS_PER_SECOND / 1000n;
+/**
+ * `hh:mm:ss.mmm`, from exact ticks.
+ *
+ * Truncates to the millisecond rather than rounding, so the printed time never names an instant
+ * later than the event. Hours are not wrapped at 24 — a 30-hour recording is a real thing and
+ * `30:12:00.000` is more useful than `06:12:00.000` on day two.
+ */
+function clock(ticks) {
+    const negative = ticks < 0n;
+    const absolute = negative ? -ticks : ticks;
+    const totalMilliseconds = absolute / TICKS_PER_MILLISECOND;
+    const milliseconds = totalMilliseconds % 1000n;
+    const totalSeconds = totalMilliseconds / 1000n;
+    const seconds = totalSeconds % 60n;
+    const totalMinutes = totalSeconds / 60n;
+    const minutes = totalMinutes % 60n;
+    const hours = totalMinutes / 60n;
+    const pad = (value, width) => String(value).padStart(width, '0');
+    return (`${negative ? '-' : ''}${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)}` +
+        `.${pad(milliseconds, 3)}`);
+}
+/** A duration in seconds, or blank. `undefined` and an explicit `0` are the same instant. */
+function duration(annotation) {
+    const ticks = annotation.durationTicks;
+    if (ticks === undefined || ticks === 0n)
+        return '';
+    return `${clock(ticks)}`;
+}
+/**
+ * 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 function formatAnnotations(annotations, options) {
+    if (annotations.length === 0)
+        return '';
+    const limit = options?.maxItems === undefined || !Number.isFinite(options.maxItems)
+        ? annotations.length
+        : Math.max(0, Math.min(annotations.length, Math.floor(options.maxItems)));
+    const rows = [];
+    for (let i = 0; i < limit; i += 1) {
+        const annotation = annotations[i];
+        if (annotation === undefined)
+            continue;
+        const parts = [
+            clock(annotation.onsetTicksFromFirstRecord),
+            duration(annotation).padEnd(12),
+            annotation.text,
+        ];
+        if (options?.includeChannel === true && annotation.channelLabel !== undefined) {
+            parts.push(`@@${annotation.channelLabel}`);
+        }
+        rows.push(parts.join('  ').trimEnd());
+    }
+    const hidden = annotations.length - limit;
+    // Always stated. A truncated listing that does not say so reads as a complete one.
+    if (hidden > 0)
+        rows.push(`... and ${hidden} more`);
+    return rows.join('\n');
+}
+//# sourceMappingURL=format-annotations.js.map

package/dist/format-annotations.js.map

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

package/dist/index.d.ts

@@ -47,6 +47,8 @@ export { annotationsAt, countAnnotationsByText, filterAnnotationsByText, filterA
 export { decodeStatusWord, getStatusSignal, readTriggers } from './biosemi.js';
 export { mergeChunks } from './chunks.js';
 export { envelopeOfSamples, readEnvelope, readEnvelopeAtResolution, toPhysicalEnvelope, } from './envelope.js';
+export type { FormatAnnotationsOptions } from './format-annotations.js';
+export { formatAnnotations } from './format-annotations.js';
 export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -59,6 +59,7 @@ export { annotationsAt, countAnnotationsByText, filterAnnotationsByText, filterA
 export { decodeStatusWord, getStatusSignal, readTriggers } from './biosemi.js';
 export { mergeChunks } from './chunks.js';
 export { envelopeOfSamples, readEnvelope, readEnvelopeAtResolution, toPhysicalEnvelope, } from './envelope.js';
+export { formatAnnotations } from './format-annotations.js';
 export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA2EH,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,gCAAgC,EAChC,gBAAgB,EAChB,OAAO,GACR,MAAM,gBAAgB,CAAC;AAExB,8EAA8E;AAC9E,2EAA2E;AAC3E,2CAA2C;AAC3C,8EAA8E;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,uBAAuB,EACvB,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEnE,8EAA8E;AAC9E,yEAAyE;AACzE,2EAA2E;AAC3E,6CAA6C;AAC7C,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,KAAK,EACL,SAAS,GACV,MAAM,mBAAmB,CAAC;AAE3B,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/sample-grid.d.ts

@@ -28,10 +28,16 @@
  * count, and are not being modest about it: the information is not in their arguments.
  *
  * So the contract is stated rather than guessed at. For a file that may be discontinuous, use
- * `index.locate(seconds)` for time to record, `segmentAt`/`gapAt` to find out whether an instant
- * has data at all, and `chunk.firstSampleIndex` for the sample index a read actually produced.
- * `contiguityOf(index)` answers which regime you are in. On a contiguous file — the common case,
- * and every plain EDF or EDF+C — these are exact and are what you want.
+ * `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf` from `sample-locate.ts`, which take
+ * the recording and can therefore see a gap. `contiguityOf(index)` answers which regime you are
+ * in. On a contiguous file — the common case, and every plain EDF or EDF+C — these are exact and
+ * are what you want.
+ *
+ * RENAMED IN 0.3.0. These three keep their behaviour and lose their misleading names: they become
+ * `gridSampleIndexAt`, `gridSampleStartTicks` and `gridSampleStartSeconds`. The `grid` prefix is
+ * the whole fix — the functions were never wrong, the names simply did not say which of two
+ * different quantities they returned, and six releases of this project were spent on exactly that
+ * confusion in other places. Nothing about the arithmetic changes.
  */
 import type { EdfSampleLocation, EdfSignal } from './types.js';
 /**
@@ -40,6 +46,11 @@ import type { EdfSampleLocation, EdfSignal } from './types.js';
  * Floor, not round: a sample covers the half-open interval from its own start to the next one's,
  * so the sample "at" a time is the one whose interval contains it. Rounding would return the
  * NEXT sample for anything past the halfway point, which puts a window boundary one sample late.
+ *
+ * @deprecated Renamed to `gridSampleIndexAt` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
  */
 export declare function sampleIndexAt(signal: EdfSignal, seconds: number, recordDurationTicks: bigint): EdfSampleLocation;
 /**
@@ -54,8 +65,18 @@ export declare function sampleIndexAt(signal: EdfSignal, seconds: number, record
  * edfcore has. Truncating would return 23,437 — a tick that lies inside sample 0 — so
  * `sampleIndexAt` would send it straight back to the previous sample. Taking the first whole
  * tick at or after the exact start keeps the two functions inverse for every index.
+ *
+ * @deprecated Renamed to `gridSampleStartTicks` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
  */
 export declare function sampleStartTicks(signal: EdfSignal, sampleIndex: number, recordDurationTicks: bigint): bigint;
-/** `sampleStartTicks` in seconds, for display. Compare ticks, not this. */
+/** `sampleStartTicks` in seconds, for display. Compare ticks, not this. *
+ * @deprecated Renamed to `gridSampleStartSeconds` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
+ */
 export declare function sampleStartSeconds(signal: EdfSignal, sampleIndex: number, recordDurationTicks: bigint): number;
 //# sourceMappingURL=sample-grid.d.ts.map

package/dist/sample-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sample-grid.d.ts","sourceRoot":"","sources":["../src/sample-grid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA0B/D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,MAAM,EACf,mBAAmB,EAAE,MAAM,GAC1B,iBAAiB,CAoBnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAcR;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAKR"}
+{"version":3,"file":"sample-grid.d.ts","sourceRoot":"","sources":["../src/sample-grid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA0B/D;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,MAAM,EACf,mBAAmB,EAAE,MAAM,GAC1B,iBAAiB,CAoBnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAcR;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,MAAM,GAC1B,MAAM,CAKR"}

package/dist/sample-grid.js

@@ -28,10 +28,16 @@
  * count, and are not being modest about it: the information is not in their arguments.
  *
  * So the contract is stated rather than guessed at. For a file that may be discontinuous, use
- * `index.locate(seconds)` for time to record, `segmentAt`/`gapAt` to find out whether an instant
- * has data at all, and `chunk.firstSampleIndex` for the sample index a read actually produced.
- * `contiguityOf(index)` answers which regime you are in. On a contiguous file — the common case,
- * and every plain EDF or EDF+C — these are exact and are what you want.
+ * `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf` from `sample-locate.ts`, which take
+ * the recording and can therefore see a gap. `contiguityOf(index)` answers which regime you are
+ * in. On a contiguous file — the common case, and every plain EDF or EDF+C — these are exact and
+ * are what you want.
+ *
+ * RENAMED IN 0.3.0. These three keep their behaviour and lose their misleading names: they become
+ * `gridSampleIndexAt`, `gridSampleStartTicks` and `gridSampleStartSeconds`. The `grid` prefix is
+ * the whole fix — the functions were never wrong, the names simply did not say which of two
+ * different quantities they returned, and six releases of this project were spent on exactly that
+ * confusion in other places. Nothing about the arithmetic changes.
  */
 import { TICKS_PER_SECOND } from './constants.js';
 import { secondsToTicks } from './tal/ticks.js';
@@ -58,6 +64,11 @@ function assertGrid(signal, recordDurationTicks) {
  * Floor, not round: a sample covers the half-open interval from its own start to the next one's,
  * so the sample "at" a time is the one whose interval contains it. Rounding would return the
  * NEXT sample for anything past the halfway point, which puts a window boundary one sample late.
+ *
+ * @deprecated Renamed to `gridSampleIndexAt` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
  */
 export function sampleIndexAt(signal, seconds, recordDurationTicks) {
     assertGrid(signal, recordDurationTicks);
@@ -90,6 +101,11 @@ export function sampleIndexAt(signal, seconds, recordDurationTicks) {
  * edfcore has. Truncating would return 23,437 — a tick that lies inside sample 0 — so
  * `sampleIndexAt` would send it straight back to the previous sample. Taking the first whole
  * tick at or after the exact start keeps the two functions inverse for every index.
+ *
+ * @deprecated Renamed to `gridSampleStartTicks` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
  */
 export function sampleStartTicks(signal, sampleIndex, recordDurationTicks) {
     assertGrid(signal, recordDurationTicks);
@@ -105,7 +121,12 @@ export function sampleStartTicks(signal, sampleIndex, recordDurationTicks) {
         return quotient;
     return numerator > 0n ? quotient + 1n : quotient;
 }
-/** `sampleStartTicks` in seconds, for display. Compare ticks, not this. */
+/** `sampleStartTicks` in seconds, for display. Compare ticks, not this. *
+ * @deprecated Renamed to `gridSampleStartSeconds` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
+ */
 export function sampleStartSeconds(signal, sampleIndex, recordDurationTicks) {
     const ticks = sampleStartTicks(signal, sampleIndex, recordDurationTicks);
     const whole = ticks / TICKS_PER_SECOND;

package/dist/sample-grid.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edfcore",
-  "version": "0.2.61",
+  "version": "0.2.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.2.61';
+export const VERSION = '0.2.63';

package/src/format-annotations.ts

@@ -0,0 +1,103 @@
+/**
+ * Annotations as text.
+ *
+ * Layer 7, and pure. `formatHeader` does this for the header and `formatDiagnostics` for problems;
+ * this is the third, and the one a hypnogram or an event list actually needs.
+ *
+ * The clock is built from `onsetTicksFromFirstRecord` by integer division, never from the float
+ * seconds. That is not fussiness: `onsetSecondsFromFirstRecord` is a float64 produced by dividing
+ * an exact tick count by 10,000,000, so an onset written `+1.0000001` can print a millisecond
+ * field that is off by one — and an event list is exactly where someone reads a number off the
+ * screen and types it into something else.
+ *
+ * A NEGATIVE onset is legal and prints as one. EDF+ measures onsets from the header start time
+ * and a recording may begin after its first annotation, so `-00:00:01.500` is a real thing a real
+ * file says. Clamping it to zero would silently move an event.
+ */
+
+import { TICKS_PER_SECOND } from './constants.js';
+import type { EdfAnnotation } from './types.js';
+
+export interface FormatAnnotationsOptions {
+  /** Rows to print. Defaults to every annotation; the count of the rest is always stated. */
+  readonly maxItems?: number;
+  /** Include the `description@@channel` label EDF+ allows. Off by default: most files have none. */
+  readonly includeChannel?: boolean;
+}
+
+const TICKS_PER_MILLISECOND = TICKS_PER_SECOND / 1000n;
+
+/**
+ * `hh:mm:ss.mmm`, from exact ticks.
+ *
+ * Truncates to the millisecond rather than rounding, so the printed time never names an instant
+ * later than the event. Hours are not wrapped at 24 — a 30-hour recording is a real thing and
+ * `30:12:00.000` is more useful than `06:12:00.000` on day two.
+ */
+function clock(ticks: bigint): string {
+  const negative = ticks < 0n;
+  const absolute = negative ? -ticks : ticks;
+
+  const totalMilliseconds = absolute / TICKS_PER_MILLISECOND;
+  const milliseconds = totalMilliseconds % 1000n;
+  const totalSeconds = totalMilliseconds / 1000n;
+  const seconds = totalSeconds % 60n;
+  const totalMinutes = totalSeconds / 60n;
+  const minutes = totalMinutes % 60n;
+  const hours = totalMinutes / 60n;
+
+  const pad = (value: bigint, width: number): string => String(value).padStart(width, '0');
+  return (
+    `${negative ? '-' : ''}${pad(hours, 2)}:${pad(minutes, 2)}:${pad(seconds, 2)}` +
+    `.${pad(milliseconds, 3)}`
+  );
+}
+
+/** A duration in seconds, or blank. `undefined` and an explicit `0` are the same instant. */
+function duration(annotation: EdfAnnotation): string {
+  const ticks = annotation.durationTicks;
+  if (ticks === undefined || ticks === 0n) return '';
+  return `${clock(ticks)}`;
+}
+
+/**
+ * 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 function formatAnnotations(
+  annotations: readonly EdfAnnotation[],
+  options?: FormatAnnotationsOptions,
+): string {
+  if (annotations.length === 0) return '';
+
+  const limit =
+    options?.maxItems === undefined || !Number.isFinite(options.maxItems)
+      ? annotations.length
+      : Math.max(0, Math.min(annotations.length, Math.floor(options.maxItems)));
+
+  const rows: string[] = [];
+  for (let i = 0; i < limit; i += 1) {
+    const annotation = annotations[i];
+    if (annotation === undefined) continue;
+    const parts = [
+      clock(annotation.onsetTicksFromFirstRecord),
+      duration(annotation).padEnd(12),
+      annotation.text,
+    ];
+    if (options?.includeChannel === true && annotation.channelLabel !== undefined) {
+      parts.push(`@@${annotation.channelLabel}`);
+    }
+    rows.push(parts.join('  ').trimEnd());
+  }
+
+  const hidden = annotations.length - limit;
+  // Always stated. A truncated listing that does not say so reads as a complete one.
+  if (hidden > 0) rows.push(`... and ${hidden} more`);
+
+  return rows.join('\n');
+}

package/src/index.ts

@@ -186,6 +186,8 @@ export {
   readEnvelopeAtResolution,
   toPhysicalEnvelope,
 } from './envelope.js';
+export type { FormatAnnotationsOptions } from './format-annotations.js';
+export { formatAnnotations } from './format-annotations.js';
 export { formatHeader } from './format-header.js';
 export { inspectEdf } from './inspect.js';
 export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';

package/src/sample-grid.ts

@@ -28,10 +28,16 @@
  * count, and are not being modest about it: the information is not in their arguments.
  *
  * So the contract is stated rather than guessed at. For a file that may be discontinuous, use
- * `index.locate(seconds)` for time to record, `segmentAt`/`gapAt` to find out whether an instant
- * has data at all, and `chunk.firstSampleIndex` for the sample index a read actually produced.
- * `contiguityOf(index)` answers which regime you are in. On a contiguous file — the common case,
- * and every plain EDF or EDF+C — these are exact and are what you want.
+ * `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf` from `sample-locate.ts`, which take
+ * the recording and can therefore see a gap. `contiguityOf(index)` answers which regime you are
+ * in. On a contiguous file — the common case, and every plain EDF or EDF+C — these are exact and
+ * are what you want.
+ *
+ * RENAMED IN 0.3.0. These three keep their behaviour and lose their misleading names: they become
+ * `gridSampleIndexAt`, `gridSampleStartTicks` and `gridSampleStartSeconds`. The `grid` prefix is
+ * the whole fix — the functions were never wrong, the names simply did not say which of two
+ * different quantities they returned, and six releases of this project were spent on exactly that
+ * confusion in other places. Nothing about the arithmetic changes.
  */
 
 import { TICKS_PER_SECOND } from './constants.js';
@@ -68,6 +74,11 @@ function assertGrid(signal: EdfSignal, recordDurationTicks: bigint): void {
  * Floor, not round: a sample covers the half-open interval from its own start to the next one's,
  * so the sample "at" a time is the one whose interval contains it. Rounding would return the
  * NEXT sample for anything past the halfway point, which puts a window boundary one sample late.
+ *
+ * @deprecated Renamed to `gridSampleIndexAt` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
  */
 export function sampleIndexAt(
   signal: EdfSignal,
@@ -107,6 +118,11 @@ export function sampleIndexAt(
  * edfcore has. Truncating would return 23,437 — a tick that lies inside sample 0 — so
  * `sampleIndexAt` would send it straight back to the previous sample. Taking the first whole
  * tick at or after the exact start keeps the two functions inverse for every index.
+ *
+ * @deprecated Renamed to `gridSampleStartTicks` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
  */
 export function sampleStartTicks(
   signal: EdfSignal,
@@ -128,7 +144,12 @@ export function sampleStartTicks(
   return numerator > 0n ? quotient + 1n : quotient;
 }
 
-/** `sampleStartTicks` in seconds, for display. Compare ticks, not this. */
+/** `sampleStartTicks` in seconds, for display. Compare ticks, not this. *
+ * @deprecated Renamed to `gridSampleStartSeconds` in 0.3.0. The behaviour is unchanged — only the
+ * name, which never said which of two different quantities it returns. For a file that may
+ * have gaps, use `sampleAt` / `sampleStartTicksOf` / `sampleStartSecondsOf`, which take the
+ * recording and can therefore see one.
+ */
 export function sampleStartSeconds(
   signal: EdfSignal,
   sampleIndex: number,