edf2csv 0.1.0

package/dist/edf/reader.js

@@ -0,0 +1,224 @@
+/**
+ * Chunked reader for EDF / EDF+ files.
+ *
+ * Data records are read in batches sized by a byte budget rather than all at once,
+ * so peak memory stays flat regardless of how long the recording is. A 4 GB file
+ * and a 4 MB file use the same working set.
+ */
+import { open, stat } from 'node:fs/promises';
+import { EdfError } from './errors.js';
+import { FIXED_HEADER_BYTES, SIGNAL_HEADER_BYTES, parseHeader } from './header.js';
+import { decodeRecordAnnotations } from './annotations.js';
+/** Default read budget per batch. Large enough to amortise syscalls, small enough to stay cheap. */
+export const DEFAULT_CHUNK_BYTES = 8 * 1024 * 1024;
+export class EdfFile {
+    path;
+    fileSize;
+    header;
+    /** Records actually present in the file, which may differ from the header's claim. */
+    recordCount;
+    trailingBytes;
+    diagnostics;
+    #handle;
+    #closed = false;
+    constructor(init) {
+        this.path = init.path;
+        this.fileSize = init.fileSize;
+        this.header = init.header;
+        this.recordCount = init.recordCount;
+        this.trailingBytes = init.trailingBytes;
+        this.diagnostics = init.diagnostics;
+        this.#handle = init.handle;
+    }
+    static async open(path) {
+        const info = await stat(path).catch((cause) => {
+            throw new EdfError('UNREADABLE', `Cannot read "${path}": ${describe(cause)}`);
+        });
+        if (info.isDirectory()) {
+            throw new EdfError('UNREADABLE', `"${path}" is a directory, not an EDF file.`);
+        }
+        if (!info.isFile()) {
+            throw new EdfError('UNREADABLE', `"${path}" is not a regular file.`);
+        }
+        const handle = await open(path, 'r');
+        try {
+            const fixed = Buffer.alloc(Math.min(FIXED_HEADER_BYTES, info.size));
+            if (fixed.length > 0) {
+                const bytesRead = await readFully(handle, fixed, 0, fixed.length, 0);
+                if (bytesRead < fixed.length)
+                    throw changedWhileReading(0, fixed.length, bytesRead);
+            }
+            // The signal count decides how much more header there is to read.
+            let headerBuffer = fixed;
+            if (fixed.length === FIXED_HEADER_BYTES) {
+                // Some writers NUL-pad this field instead of space-padding it, and String.trim
+                // does not remove NULs — leaving the whole header unreadable for a valid file.
+                const ns = Number(fixed.subarray(252, 256).toString('latin1').replace(/[\0\s]/gu, ''));
+                if (Number.isInteger(ns) && ns > 0) {
+                    const total = FIXED_HEADER_BYTES + ns * SIGNAL_HEADER_BYTES;
+                    if (total <= info.size) {
+                        headerBuffer = Buffer.alloc(total);
+                        const bytesRead = await readFully(handle, headerBuffer, 0, total, 0);
+                        if (bytesRead < total)
+                            throw changedWhileReading(0, total, bytesRead);
+                    }
+                }
+            }
+            const { header, recordCount, trailingBytes, diagnostics } = parseHeader(headerBuffer, info.size);
+            return new EdfFile({
+                path,
+                fileSize: info.size,
+                header,
+                recordCount,
+                trailingBytes,
+                diagnostics,
+                handle,
+            });
+        }
+        catch (error) {
+            await handle.close().catch(() => { });
+            throw error;
+        }
+    }
+    /** Signal channels, excluding the EDF+ annotations channel. */
+    get dataSignals() {
+        return this.header.signals.filter((s) => !s.isAnnotations);
+    }
+    get annotationSignals() {
+        return this.header.signals.filter((s) => s.isAnnotations);
+    }
+    /** Total recording duration in seconds, based on records actually present. */
+    get durationSeconds() {
+        return this.recordCount * this.header.recordDuration;
+    }
+    /** Read a half-open range of records in batches. */
+    async *readRecords(options = {}) {
+        this.#assertOpen();
+        const start = Math.max(0, options.startRecord ?? 0);
+        const end = Math.min(this.recordCount, options.endRecord ?? this.recordCount);
+        if (start >= end)
+            return;
+        const { recordBytes } = this.header;
+        const budget = options.chunkBytes ?? DEFAULT_CHUNK_BYTES;
+        const perChunk = Math.max(1, Math.floor(budget / recordBytes));
+        const buffer = Buffer.alloc(perChunk * recordBytes);
+        for (let record = start; record < end; record += perChunk) {
+            const count = Math.min(perChunk, end - record);
+            const bytes = count * recordBytes;
+            const position = this.header.headerBytes + record * recordBytes;
+            const bytesRead = await readFully(this.#handle, buffer, 0, bytes, position);
+            if (bytesRead < bytes) {
+                // The file is shorter than its own size said. Quietly stopping here would
+                // hand back a conversion missing its tail with nothing to show for it.
+                throw new EdfError('UNREADABLE', `Expected ${bytes} bytes of data at record ${record} but only ${bytesRead} were ` +
+                    `available; the file appears to have changed size while it was being read.`, 'Make sure the recording is not still being written to, then try again.');
+            }
+            yield { firstRecordIndex: record, recordCount: count, data: buffer.subarray(0, bytes) };
+        }
+    }
+    /** Read one sample as its raw digital value. */
+    sampleAt(batch, recordOffset, signal, sampleIndex) {
+        const position = recordOffset * this.header.recordBytes +
+            signal.byteOffsetInRecord +
+            sampleIndex * this.header.bytesPerSample;
+        if (this.header.bytesPerSample === 3) {
+            // BDF stores 24-bit little-endian two's complement. Loading the three bytes
+            // into the top of a 32-bit word and shifting back down sign-extends them.
+            const data = batch.data;
+            return ((data[position] << 8) |
+                (data[position + 1] << 16) |
+                (data[position + 2] << 24)) >> 8;
+        }
+        return batch.data.readInt16LE(position);
+    }
+    /** Byte offset of a signal's samples within a batch. */
+    offsetOf(batch, recordOffset, signal) {
+        return recordOffset * this.header.recordBytes + signal.byteOffsetInRecord;
+    }
+    /** The annotation channel's raw bytes for one record in a batch. */
+    annotationBytes(batch, recordOffset, signal) {
+        const start = this.offsetOf(batch, recordOffset, signal);
+        return batch.data.subarray(start, start + signal.samplesPerRecord * this.header.bytesPerSample);
+    }
+    /**
+     * Read every EDF+ annotation in the file, plus the start time each record declares.
+     *
+     * Only the annotation channel is read, seeking straight to it inside each record
+     * rather than pulling whole records through memory. On a multi-gigabyte recording
+     * that is the difference between a few kilobytes of I/O and all of it.
+     *
+     * The whole file is always scanned, never just the records inside a requested
+     * window: writers are not obliged to store an annotation in the record its onset
+     * falls in, and some put every annotation in the first record. Reading only the
+     * window's records would drop those entirely.
+     */
+    async readAnnotations() {
+        this.#assertOpen();
+        const annotations = [];
+        const recordStarts = new Array(this.recordCount).fill(null);
+        let malformed = 0;
+        const channels = this.annotationSignals;
+        if (channels.length === 0)
+            return { annotations, recordStarts, malformed };
+        const { headerBytes, recordBytes, bytesPerSample } = this.header;
+        const buffers = channels.map((c) => Buffer.alloc(c.samplesPerRecord * bytesPerSample));
+        for (let record = 0; record < this.recordCount; record++) {
+            for (const [position, channel] of channels.entries()) {
+                const buffer = buffers[position];
+                if (!buffer || buffer.length === 0)
+                    continue;
+                const offset = headerBytes + record * recordBytes + channel.byteOffsetInRecord;
+                const bytesRead = await readFully(this.#handle, buffer, 0, buffer.length, offset);
+                if (bytesRead < buffer.length) {
+                    throw changedWhileReading(record, buffer.length, bytesRead, 'annotation data');
+                }
+                const decoded = decodeRecordAnnotations(buffer, record);
+                // Only the first annotation channel carries the record's timekeeping TAL.
+                if (position === 0)
+                    recordStarts[record] = decoded.recordStart;
+                for (const annotation of decoded.annotations)
+                    annotations.push(annotation);
+                malformed += decoded.malformed;
+            }
+        }
+        annotations.sort((a, b) => a.onset - b.onset || a.recordIndex - b.recordIndex);
+        return { annotations, recordStarts, malformed };
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.#handle.close();
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new EdfError('UNREADABLE', 'This EDF file has already been closed.');
+    }
+}
+function describe(cause) {
+    if (cause instanceof Error) {
+        const code = cause.code;
+        if (code === 'ENOENT')
+            return 'no such file';
+        if (code === 'EACCES')
+            return 'permission denied';
+        return cause.message;
+    }
+    return String(cause);
+}
+/** Fill a requested region unless EOF is reached; regular-file reads may legally be short. */
+async function readFully(handle, buffer, offset, length, position) {
+    let total = 0;
+    while (total < length) {
+        const { bytesRead } = await handle.read(buffer, offset + total, length - total, position + total);
+        if (bytesRead === 0)
+            break;
+        total += bytesRead;
+    }
+    return total;
+}
+function changedWhileReading(record, expected, actual, subject = 'data') {
+    return new EdfError('UNREADABLE', `Expected ${expected} bytes of ${subject} at record ${record} but only ${actual} were ` +
+        `available; the file appears to have changed size while it was being read.`, 'Make sure the recording is not still being written to, then try again.');
+}
+//# sourceMappingURL=reader.js.map

package/dist/edf/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../src/edf/reader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,oGAAoG;AACpG,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAuBnD,MAAM,OAAO,OAAO;IACT,IAAI,CAAS;IACb,QAAQ,CAAS;IACjB,MAAM,CAAY;IAC3B,sFAAsF;IAC7E,WAAW,CAAS;IACpB,aAAa,CAAS;IACtB,WAAW,CAAe;IAEnC,OAAO,CAAa;IACpB,OAAO,GAAG,KAAK,CAAC;IAEhB,YAAoB,IAQnB;QACC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAY;QAC5B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACrD,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,gBAAgB,IAAI,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC,CAAC,CAAC;QACH,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,IAAI,IAAI,oCAAoC,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,IAAI,IAAI,0BAA0B,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YACpE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;gBACrE,IAAI,SAAS,GAAG,KAAK,CAAC,MAAM;oBAAE,MAAM,mBAAmB,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACtF,CAAC;YAED,kEAAkE;YAClE,IAAI,YAAY,GAAG,KAAK,CAAC;YACzB,IAAI,KAAK,CAAC,MAAM,KAAK,kBAAkB,EAAE,CAAC;gBACxC,+EAA+E;gBAC/E,+EAA+E;gBAC/E,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;gBACvF,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;oBACnC,MAAM,KAAK,GAAG,kBAAkB,GAAG,EAAE,GAAG,mBAAmB,CAAC;oBAC5D,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;wBACvB,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;wBACnC,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;wBACrE,IAAI,SAAS,GAAG,KAAK;4BAAE,MAAM,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;oBACxE,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,GAAG,WAAW,CACrE,YAAY,EACZ,IAAI,CAAC,IAAI,CACV,CAAC;YAEF,OAAO,IAAI,OAAO,CAAC;gBACjB,IAAI;gBACJ,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,MAAM;gBACN,WAAW;gBACX,aAAa;gBACb,WAAW;gBACX,MAAM;aACP,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACrC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC7D,CAAC;IAED,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAC5D,CAAC;IAED,8EAA8E;IAC9E,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;IACvD,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,CAAC,WAAW,CAAC,UAA8B,EAAE;QACjD,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9E,IAAI,KAAK,IAAI,GAAG;YAAE,OAAO;QAEzB,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACpC,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,WAAW,CAAC,CAAC;QAEpD,KAAK,IAAI,MAAM,GAAG,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,CAAC,CAAC;YAC/C,MAAM,KAAK,GAAG,KAAK,GAAG,WAAW,CAAC;YAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC;YAEhE,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;YAC5E,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;gBACtB,0EAA0E;gBAC1E,uEAAuE;gBACvE,MAAM,IAAI,QAAQ,CAChB,YAAY,EACZ,YAAY,KAAK,4BAA4B,MAAM,aAAa,SAAS,QAAQ;oBAC/E,2EAA2E,EAC7E,wEAAwE,CACzE,CAAC;YACJ,CAAC;YAED,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QAC1F,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,QAAQ,CAAC,KAAkB,EAAE,YAAoB,EAAE,MAAiB,EAAE,WAAmB;QACvF,MAAM,QAAQ,GACZ,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW;YACtC,MAAM,CAAC,kBAAkB;YACzB,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;QAE3C,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;YACrC,4EAA4E;YAC5E,0EAA0E;YAC1E,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACxB,OAAO,CACL,CAAE,IAAI,CAAC,QAAQ,CAAY,IAAI,CAAC,CAAC;gBACjC,CAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;gBACtC,CAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC,CACvC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,wDAAwD;IACxD,QAAQ,CAAC,KAAkB,EAAE,YAAoB,EAAE,MAAiB;QAClE,OAAO,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,kBAAkB,CAAC;IAC5E,CAAC;IAED,oEAAoE;IACpE,eAAe,CAAC,KAAkB,EAAE,YAAoB,EAAE,MAAiB;QACzE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;QACzD,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAClG,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,eAAe;QAKnB,IAAI,CAAC,WAAW,EAAE,CAAC;QAEnB,MAAM,WAAW,GAAiB,EAAE,CAAC;QACrC,MAAM,YAAY,GAAsB,IAAI,KAAK,CAAgB,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9F,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC;QACxC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;QAE3E,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACjE,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAC,CAAC;QAEvF,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;YACzD,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;gBACrD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACjC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;oBAAE,SAAS;gBAE7C,MAAM,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;gBAC/E,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAClF,IAAI,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC9B,MAAM,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC;gBACjF,CAAC;gBAED,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBACxD,0EAA0E;gBAC1E,IAAI,QAAQ,KAAK,CAAC;oBAAE,YAAY,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;gBAC/D,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,WAAW;oBAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAC3E,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;YACjC,CAAC;QACH,CAAC;QAED,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;QAC/E,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED,WAAW;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,QAAQ,CAAC,YAAY,EAAE,wCAAwC,CAAC,CAAC;IAC/F,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAI,KAA+B,CAAC,IAAI,CAAC;QACnD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,cAAc,CAAC;QAC7C,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,mBAAmB,CAAC;QAClD,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,8FAA8F;AAC9F,KAAK,UAAU,SAAS,CACtB,MAAkB,EAClB,MAAc,EACd,MAAc,EACd,MAAc,EACd,QAAgB;IAEhB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,MAAM,EAAE,CAAC;QACtB,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CACrC,MAAM,EACN,MAAM,GAAG,KAAK,EACd,MAAM,GAAG,KAAK,EACd,QAAQ,GAAG,KAAK,CACjB,CAAC;QACF,IAAI,SAAS,KAAK,CAAC;YAAE,MAAM;QAC3B,KAAK,IAAI,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,mBAAmB,CAC1B,MAAc,EACd,QAAgB,EAChB,MAAc,EACd,OAAO,GAAG,MAAM;IAEhB,OAAO,IAAI,QAAQ,CACjB,YAAY,EACZ,YAAY,QAAQ,aAAa,OAAO,cAAc,MAAM,aAAa,MAAM,QAAQ;QACrF,2EAA2E,EAC7E,wEAAwE,CACzE,CAAC;AACJ,CAAC"}

package/dist/edf/scale.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Digital-to-physical conversion.
+ *
+ * EDF defines the mapping by two calibration points, (digitalMin -> physicalMin)
+ * and (digitalMax -> physicalMax), which the specification writes as:
+ *
+ *   gain     = (physicalMax - physicalMin) / (digitalMax - digitalMin)
+ *   physical = (digital - digitalMin) * gain + physicalMin
+ *
+ * That form is evaluated here in EDFlib's algebraically equivalent arrangement:
+ *
+ *   offset   = physicalMax / gain - digitalMax
+ *   physical = gain * (offset + digital)
+ *
+ * The rearrangement is not cosmetic. Written the first way, a channel spanning
+ * +/-800 uV computes a value near 800 and then subtracts 800, and the cancellation
+ * throws away low-order bits: digital 0 yields 0.19536019536019467 when the exact
+ * value is 0.19536019536019536. EDFlib's form keeps the intermediate small
+ * (offset + digital = 0.5 here) and returns the correctly rounded result.
+ *
+ * Both properties matter. The values are as accurate as a double can express, and
+ * they are bit-identical to pyEDFlib and EDFbrowser, which share EDFlib's arithmetic,
+ * so the test suite can assert exact equality against a reference implementation
+ * rather than settling for a tolerance.
+ */
+import type { EdfSignal } from './header.js';
+export type Scaler = (digital: number) => number;
+export declare function makeScaler(signal: EdfSignal): Scaler;
+/**
+ * Smallest physical step this channel can express — one digital unit.
+ * Used to choose a decimal precision that preserves every distinct sample value.
+ */
+export declare function quantizationStep(signal: EdfSignal): number;
+/**
+ * Decimal places needed so that two adjacent digital codes never round to the same
+ * string. Two places past the quantization step keep rounding error far below the
+ * resolution the hardware actually recorded, without padding the file with digits
+ * that carry no information.
+ *
+ * The ceiling is 15 rather than a tidier number because a channel calibrated in
+ * volts rather than microvolts has a step near 1e-7, and one in tesla smaller
+ * still. A lower cap would round genuinely different samples to the same text. It
+ * costs nothing for ordinary channels, whose step lands them at three or four.
+ */
+export declare function decimalsForSignal(signal: EdfSignal, max?: number): number;
+//# sourceMappingURL=scale.d.ts.map

package/dist/edf/scale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scale.d.ts","sourceRoot":"","sources":["../../src/edf/scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAEjD,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAwBpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAI1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAK,GAAG,MAAM,CAKrE"}

package/dist/edf/scale.js

@@ -0,0 +1,76 @@
+/**
+ * Digital-to-physical conversion.
+ *
+ * EDF defines the mapping by two calibration points, (digitalMin -> physicalMin)
+ * and (digitalMax -> physicalMax), which the specification writes as:
+ *
+ *   gain     = (physicalMax - physicalMin) / (digitalMax - digitalMin)
+ *   physical = (digital - digitalMin) * gain + physicalMin
+ *
+ * That form is evaluated here in EDFlib's algebraically equivalent arrangement:
+ *
+ *   offset   = physicalMax / gain - digitalMax
+ *   physical = gain * (offset + digital)
+ *
+ * The rearrangement is not cosmetic. Written the first way, a channel spanning
+ * +/-800 uV computes a value near 800 and then subtracts 800, and the cancellation
+ * throws away low-order bits: digital 0 yields 0.19536019536019467 when the exact
+ * value is 0.19536019536019536. EDFlib's form keeps the intermediate small
+ * (offset + digital = 0.5 here) and returns the correctly rounded result.
+ *
+ * Both properties matter. The values are as accurate as a double can express, and
+ * they are bit-identical to pyEDFlib and EDFbrowser, which share EDFlib's arithmetic,
+ * so the test suite can assert exact equality against a reference implementation
+ * rather than settling for a tolerance.
+ */
+export function makeScaler(signal) {
+    const { digitalMin, digitalMax, physicalMin, physicalMax } = signal;
+    // A zero digital span leaves the mapping undefined — the header contradicts itself.
+    // Reporting the physical minimum is the least misleading answer, and the header
+    // parser has already raised DEGENERATE_DIGITAL_RANGE so the user is not misled.
+    if (digitalMax === digitalMin)
+        return () => physicalMin;
+    const gain = (physicalMax - physicalMin) / (digitalMax - digitalMin);
+    // A flat physical range makes every sample the same value, and would divide by
+    // zero in the offset below.
+    if (gain === 0 || !Number.isFinite(gain))
+        return () => physicalMin;
+    // Deriving the offset divides by the gain. For every realistic calibration that is
+    // both safe and more accurate, but an absurd header (a huge physical range over a
+    // near-zero gain) could overflow it, so fall back to the specification's own
+    // arrangement rather than emitting Infinity.
+    const offset = physicalMax / gain - digitalMax;
+    if (!Number.isFinite(offset)) {
+        return (digital) => (digital - digitalMin) * gain + physicalMin;
+    }
+    return (digital) => gain * (offset + digital);
+}
+/**
+ * Smallest physical step this channel can express — one digital unit.
+ * Used to choose a decimal precision that preserves every distinct sample value.
+ */
+export function quantizationStep(signal) {
+    const digitalSpan = signal.digitalMax - signal.digitalMin;
+    if (digitalSpan === 0)
+        return 0;
+    return Math.abs((signal.physicalMax - signal.physicalMin) / digitalSpan);
+}
+/**
+ * Decimal places needed so that two adjacent digital codes never round to the same
+ * string. Two places past the quantization step keep rounding error far below the
+ * resolution the hardware actually recorded, without padding the file with digits
+ * that carry no information.
+ *
+ * The ceiling is 15 rather than a tidier number because a channel calibrated in
+ * volts rather than microvolts has a step near 1e-7, and one in tesla smaller
+ * still. A lower cap would round genuinely different samples to the same text. It
+ * costs nothing for ordinary channels, whose step lands them at three or four.
+ */
+export function decimalsForSignal(signal, max = 15) {
+    const step = quantizationStep(signal);
+    if (!(step > 0) || !Number.isFinite(step))
+        return 3;
+    const needed = Math.ceil(-Math.log10(step)) + 2;
+    return Math.min(max, Math.max(0, needed));
+}
+//# sourceMappingURL=scale.js.map

package/dist/edf/scale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scale.js","sourceRoot":"","sources":["../../src/edf/scale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,MAAM,UAAU,UAAU,CAAC,MAAiB;IAC1C,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IAEpE,oFAAoF;IACpF,gFAAgF;IAChF,gFAAgF;IAChF,IAAI,UAAU,KAAK,UAAU;QAAE,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC;IAExD,MAAM,IAAI,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC,CAAC;IAErE,+EAA+E;IAC/E,4BAA4B;IAC5B,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC;IAEnE,mFAAmF;IACnF,kFAAkF;IAClF,6EAA6E;IAC7E,6CAA6C;IAC7C,MAAM,MAAM,GAAG,WAAW,GAAG,IAAI,GAAG,UAAU,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,OAAe,EAAU,EAAE,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC,GAAG,IAAI,GAAG,WAAW,CAAC;IAClF,CAAC;IAED,OAAO,CAAC,OAAe,EAAU,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAiB;IAChD,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAC1D,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,GAAG,GAAG,EAAE;IAC3D,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/format/csv.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CSV escaping and a buffered, backpressure-aware line writer.
+ *
+ * Rows are accumulated in memory and flushed in large blocks. Writing row by row
+ * would issue millions of small stream writes, and ignoring the return value of
+ * `write()` would let Node buffer the entire output in RAM — which for an hour of
+ * 23-channel EEG is several hundred megabytes.
+ */
+import type { Writable } from 'node:stream';
+/** Quote a field only when CSV requires it, doubling any embedded quotes. */
+export declare function escapeCsvField(value: string): string;
+export declare function csvRow(cells: readonly string[]): string;
+/**
+ * Accumulates text and flushes it to a stream, respecting backpressure.
+ *
+ * Call `push()` freely, then `await maybeFlush()` at a row boundary. Memory stays
+ * bounded by the flush threshold plus whatever the stream has not yet drained.
+ */
+export declare class BufferedLineWriter {
+    #private;
+    constructor(stream: Writable, threshold?: number);
+    /** Characters written to the stream so far, before any encoding expansion. */
+    get charsWritten(): number;
+    push(text: string): void;
+    pushLine(text: string): void;
+    /** Flush if enough has accumulated. Await this at row boundaries. */
+    maybeFlush(): Promise<void>;
+    flush(): Promise<void>;
+    /** Flush anything left and close the stream. */
+    end(): Promise<void>;
+    /** Close the stream without caring whether the data made it out. */
+    destroy(): void;
+}
+//# sourceMappingURL=csv.d.ts.map

package/dist/format/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/format/csv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQ5C,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;;gBASjB,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAE,MAAgC;IAWzE,8EAA8E;IAC9E,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B,qEAAqE;IAC/D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C5B,gDAAgD;IAC1C,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAe1B,oEAAoE;IACpE,OAAO,IAAI,IAAI;CAOhB"}

package/dist/format/csv.js

@@ -0,0 +1,136 @@
+/**
+ * CSV escaping and a buffered, backpressure-aware line writer.
+ *
+ * Rows are accumulated in memory and flushed in large blocks. Writing row by row
+ * would issue millions of small stream writes, and ignoring the return value of
+ * `write()` would let Node buffer the entire output in RAM — which for an hour of
+ * 23-channel EEG is several hundred megabytes.
+ */
+import { once } from 'node:events';
+/** Flush once this many characters have accumulated. */
+const DEFAULT_FLUSH_THRESHOLD = 1 << 20; // 1 MiB
+const NEEDS_QUOTING = /[",\r\n]/u;
+/** Quote a field only when CSV requires it, doubling any embedded quotes. */
+export function escapeCsvField(value) {
+    if (value === '')
+        return '';
+    if (!NEEDS_QUOTING.test(value))
+        return value;
+    return `"${value.replaceAll('"', '""')}"`;
+}
+export function csvRow(cells) {
+    return cells.map(escapeCsvField).join(',');
+}
+/**
+ * Accumulates text and flushes it to a stream, respecting backpressure.
+ *
+ * Call `push()` freely, then `await maybeFlush()` at a row boundary. Memory stays
+ * bounded by the flush threshold plus whatever the stream has not yet drained.
+ */
+export class BufferedLineWriter {
+    #stream;
+    #parts = [];
+    #pending = 0;
+    #threshold;
+    #bytesWritten = 0;
+    #ended = false;
+    #failure = null;
+    constructor(stream, threshold = DEFAULT_FLUSH_THRESHOLD) {
+        this.#stream = stream;
+        this.#threshold = threshold;
+        // A stream with no 'error' listener throws asynchronously and takes the whole
+        // process down with a raw stack trace. Capturing the error here lets the next
+        // flush surface it as a normal failure with a usable message.
+        this.#stream.on('error', (error) => {
+            this.#failure ??= error;
+        });
+    }
+    /** Characters written to the stream so far, before any encoding expansion. */
+    get charsWritten() {
+        return this.#bytesWritten;
+    }
+    push(text) {
+        this.#parts.push(text);
+        this.#pending += text.length;
+    }
+    pushLine(text) {
+        this.push(text);
+        this.push('\n');
+    }
+    /** Flush if enough has accumulated. Await this at row boundaries. */
+    async maybeFlush() {
+        if (this.#pending >= this.#threshold)
+            await this.flush();
+    }
+    async flush() {
+        if (this.#failure)
+            throw this.#failure;
+        if (this.#parts.length === 0)
+            return;
+        const chunk = this.#parts.join('');
+        this.#parts = [];
+        this.#pending = 0;
+        this.#bytesWritten += chunk.length;
+        if (!this.#stream.write(chunk)) {
+            // The consumer is behind; wait rather than letting Node buffer without bound.
+            // Waiting only on 'drain' would hang forever if the stream fails instead.
+            await this.#drain();
+        }
+    }
+    /** Resolve on 'drain', reject if the stream fails first. */
+    async #drain() {
+        if (this.#failure)
+            throw this.#failure;
+        await new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.#stream.off('drain', onDrain);
+                this.#stream.off('error', onError);
+                this.#stream.off('close', onClose);
+            };
+            const onDrain = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const onClose = () => {
+                cleanup();
+                reject(this.#failure ?? new Error('The output stream closed before the data was written.'));
+            };
+            this.#stream.once('drain', onDrain);
+            this.#stream.once('error', onError);
+            this.#stream.once('close', onClose);
+        });
+    }
+    /** Flush anything left and close the stream. */
+    async end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        await this.flush();
+        // stdout must not be closed; ending it would break piping for the rest of the process.
+        if (this.#stream === process.stdout || this.#stream === process.stderr)
+            return;
+        await new Promise((resolve, reject) => {
+            this.#stream.end((error) => {
+                const failure = error ?? this.#failure;
+                if (failure)
+                    reject(failure);
+                else
+                    resolve();
+            });
+        });
+    }
+    /** Close the stream without caring whether the data made it out. */
+    destroy() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#parts = [];
+        this.#pending = 0;
+        this.#stream.destroy();
+    }
+}
+//# sourceMappingURL=csv.js.map

package/dist/format/csv.js.map

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

package/dist/format/number.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Number formatting for CSV cells.
+ *
+ * A one-hour, 23-channel, 256 Hz recording is about 21 million numeric cells, so
+ * this is the hottest code in a conversion. Two things keep it cheap:
+ *
+ *  - Every sample in a channel comes from a bounded set of integers (digitalMin to
+ *    digitalMax, typically 4096 distinct values for a 12-bit ADC). The formatted
+ *    text for a digital code never changes, so it is computed once and reused.
+ *  - The cache fills lazily. Real recordings visit only a fraction of the range,
+ *    and a channel with an implausibly wide range falls back to direct formatting
+ *    rather than reserving memory it will never use.
+ */
+import type { EdfSignal } from '../edf/header.js';
+/**
+ * Format with a fixed number of decimals, normalising negative zero.
+ *
+ * Without this, a sample that scales to a very small negative value prints as
+ * "-0.000", which looks like a distinct measurement but is not.
+ */
+export declare function fixed(value: number, decimals: number): string;
+/** Maps a raw digital sample to its formatted physical value. */
+export type SampleFormatter = (digital: number) => string;
+export declare function makeSampleFormatter(signal: EdfSignal, decimals: number): SampleFormatter;
+/**
+ * Decimals for the time column.
+ *
+ * The interval between samples is 1/rate, which has a terminating decimal
+ * expansion of d places exactly when 10^d divides evenly by the rate. Every rate
+ * in common use clears this — 256 Hz needs 8 places, 512 Hz needs 9, 250 Hz and
+ * 1000 Hz need 3 — so sample times are written exactly rather than rounded, and
+ * `time_s * rate` comes back as a whole number instead of 8191.999999.
+ *
+ * Rates with a repeating expansion (3 Hz, say) fall back to enough places to keep
+ * consecutive samples distinct.
+ */
+export declare function timeDecimals(samplingRate: number): number;
+/** Human-readable byte size for warnings and summaries. */
+export declare function formatBytes(bytes: number): string;
+/** Human-readable duration: 1h 05m 12s. */
+export declare function formatDuration(seconds: number): string;
+//# sourceMappingURL=number.d.ts.map

package/dist/format/number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../src/format/number.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAMlD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU7D;AAED,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAE1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAyBxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAStD"}