edfcore 0.1.0

package/dist/io/read.js.map

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

package/dist/io/source.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `ByteSource` contract guard.
+ *
+ * Layer 5, and the only file in `io/` that imports an error class. Nothing here knows anything
+ * about EDF.
+ *
+ * The contract is one sentence — a read resolves with EXACTLY `length` bytes or rejects, it
+ * never pads and never truncates — and it is *checked on every call*, including calls into a
+ * source the caller wrote. A source that quietly returns a short buffer is indistinguishable
+ * from a truncated file, so without this guard the parser would confidently report the wrong
+ * cause for the wrong thing.
+ */
+import type { ReadOptions } from '../types.js';
+/**
+ * Enforces the exact-length contract and returns the value unchanged so it can wrap a read
+ * expression directly.
+ */
+export declare function assertExactRead(received: Uint8Array, offset: number, length: number): Uint8Array;
+/**
+ * Validates a requested range against the source length, with the real numbers in the message.
+ *
+ * Offsets are plain JS numbers throughout edfcore — exact to 2^53 — so this checks
+ * safe-integer-ness rather than truncating with `| 0`, which silently wraps past 2 GiB.
+ */
+export declare function assertReadRange(offset: number, length: number, byteLength: number): void;
+/**
+ * Aborts a read when the caller's signal is already aborted.
+ *
+ * `DOMException` cannot be named without the DOM lib, and the thing consumers actually branch
+ * on is `error.name === 'AbortError'`, so that is what this produces.
+ */
+export declare function throwIfAborted(options?: ReadOptions): void;
+//# sourceMappingURL=source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/io/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAY/C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAYhG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAuBxF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAK1D"}

package/dist/io/source.js

@@ -0,0 +1,72 @@
+/**
+ * The `ByteSource` contract guard.
+ *
+ * Layer 5, and the only file in `io/` that imports an error class. Nothing here knows anything
+ * about EDF.
+ *
+ * The contract is one sentence — a read resolves with EXACTLY `length` bytes or rejects, it
+ * never pads and never truncates — and it is *checked on every call*, including calls into a
+ * source the caller wrote. A source that quietly returns a short buffer is indistinguishable
+ * from a truncated file, so without this guard the parser would confidently report the wrong
+ * cause for the wrong thing.
+ */
+import { EdfSourceError } from '../errors.js';
+/**
+ * A misbehaving source may resolve with something that is not a byte array at all, which is
+ * why `EdfSourceError.receivedLength` is `number | undefined` rather than `number`.
+ */
+function receivedLengthOf(received) {
+    if (received === null || received === undefined)
+        return undefined;
+    const length = received.length;
+    return typeof length === 'number' ? length : undefined;
+}
+/**
+ * Enforces the exact-length contract and returns the value unchanged so it can wrap a read
+ * expression directly.
+ */
+export function assertExactRead(received, offset, length) {
+    const receivedLength = receivedLengthOf(received);
+    if (receivedLength === length)
+        return received;
+    const got = receivedLength === undefined ? 'a value that is not a byte array' : `${receivedLength} bytes`;
+    throw new EdfSourceError(`ByteSource.read(offset ${offset}, length ${length}) resolved with ${got}. A ByteSource ` +
+        'must resolve with exactly the requested number of bytes or reject: padding or ' +
+        'truncating makes a short read indistinguishable from a truncated file. Next: make ' +
+        'read() loop until `length` bytes have arrived, and reject if they never do.', { offset, requestedLength: length, receivedLength });
+}
+/**
+ * Validates a requested range against the source length, with the real numbers in the message.
+ *
+ * Offsets are plain JS numbers throughout edfcore — exact to 2^53 — so this checks
+ * safe-integer-ness rather than truncating with `| 0`, which silently wraps past 2 GiB.
+ */
+export function assertReadRange(offset, length, byteLength) {
+    if (!Number.isSafeInteger(offset) || offset < 0) {
+        throw new EdfSourceError(`ByteSource.read was given offset ${offset}, which is not a non-negative safe integer. ` +
+            'Next: pass a plain integer byte offset; edfcore never truncates offsets to 32 bits.', { offset, requestedLength: length });
+    }
+    if (!Number.isSafeInteger(length) || length < 0) {
+        throw new EdfSourceError(`ByteSource.read was given length ${length}, which is not a non-negative safe integer. ` +
+            'Next: pass a plain integer byte count.', { offset, requestedLength: length });
+    }
+    if (offset + length > byteLength) {
+        throw new EdfSourceError(`ByteSource.read(offset ${offset}, length ${length}) ends at byte ${offset + length}, ` +
+            `past the end of a ${byteLength}-byte source. Next: clamp the request, or check that ` +
+            'the source was built over the whole file rather than a prefix of it.', { offset, requestedLength: length });
+    }
+}
+/**
+ * Aborts a read when the caller's signal is already aborted.
+ *
+ * `DOMException` cannot be named without the DOM lib, and the thing consumers actually branch
+ * on is `error.name === 'AbortError'`, so that is what this produces.
+ */
+export function throwIfAborted(options) {
+    if (options?.signal?.aborted !== true)
+        return;
+    const error = new Error('The read was aborted through options.signal.');
+    error.name = 'AbortError';
+    throw error;
+}
+//# sourceMappingURL=source.js.map

package/dist/io/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/io/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C;;;GAGG;AACH,SAAS,gBAAgB,CAAC,QAAiB;IACzC,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,MAAM,GAAI,QAAiC,CAAC,MAAM,CAAC;IACzD,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAoB,EAAE,MAAc,EAAE,MAAc;IAClF,MAAM,cAAc,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,cAAc,KAAK,MAAM;QAAE,OAAO,QAAQ,CAAC;IAC/C,MAAM,GAAG,GACP,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,kCAAkC,CAAC,CAAC,CAAC,GAAG,cAAc,QAAQ,CAAC;IAChG,MAAM,IAAI,cAAc,CACtB,0BAA0B,MAAM,YAAY,MAAM,mBAAmB,GAAG,iBAAiB;QACvF,gFAAgF;QAChF,oFAAoF;QACpF,6EAA6E,EAC/E,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,CACpD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,MAAc,EAAE,UAAkB;IAChF,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,cAAc,CACtB,oCAAoC,MAAM,8CAA8C;YACtF,qFAAqF,EACvF,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CACpC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,cAAc,CACtB,oCAAoC,MAAM,8CAA8C;YACtF,wCAAwC,EAC1C,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CACpC,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,MAAM,GAAG,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,cAAc,CACtB,0BAA0B,MAAM,YAAY,MAAM,kBAAkB,MAAM,GAAG,MAAM,IAAI;YACrF,qBAAqB,UAAU,uDAAuD;YACtF,sEAAsE,EACxE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CACpC,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAqB;IAClD,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI;QAAE,OAAO;IAC9C,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IACxE,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC;IAC1B,MAAM,KAAK,CAAC;AACd,CAAC"}

package/dist/node.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The Node adapters — the ONLY module in edfcore that imports anything from `node:`.
+ *
+ * Layer 7, published as `edfcore/node`. Keeping the import in exactly one file is what lets the
+ * universal entry (`edfcore`) be bundled for a browser without a polyfill and without a
+ * resolution alias, and a packaging test greps the built universal bundle for `node:` to prove it.
+ *
+ * Two decisions are load-bearing.
+ *
+ * 1. Reads are POSITIONAL and LOOP. `FileHandle.read` is allowed to return fewer bytes than asked
+ *    — a signal interrupted the syscall, the file lives on a network mount — and a `ByteSource`
+ *    that passed a short buffer on would be indistinguishable from a truncated file. The loop
+ *    runs until `length` bytes have arrived; a genuine end of file falls out as an
+ *    `EdfSourceError` naming both counts.
+ * 2. `fs.openAsBlob` is NEVER used, however tempting `blobSource(await openAsBlob(path))` looks.
+ *    It reports `size` modulo 2**32 and yields zeros above 4 GiB, which turns a 13 GB BDF into a
+ *    file that reads as silence with no error anywhere.
+ *
+ * TYPING. `src/` compiles with `types: []`, so `@types/node` is not available and must never be:
+ * the published `.d.ts` may not reference it, or every consumer inherits a dependency on it. The
+ * import below is therefore UNTYPED, and the minimal structural shape edfcore needs is declared
+ * here instead — `FileHandleLike` and `NodeFsPromises`. A standing CI job compiles a consumer
+ * against the real `@types/node` and asserts `fs.promises.FileHandle` is still assignable, which
+ * is what stops the two drifting.
+ *
+ * The suppression on the import is the unconditional `ts-ignore` directive rather than
+ * `@ts-expect-error`, and that is not laziness. Whether the specifier resolves depends on whether
+ * a `@types/node` happens to be reachable at all: `tsconfig.build.json` compiles `src/` alone and
+ * it is not, while `tsconfig.json` also pulls in a dev tool carrying a triple-slash reference to
+ * it and it may be. `@ts-expect-error` errors for being UNUSED in the second case, so it would
+ * break whichever of the two configurations the machine happens to disagree with.
+ */
+import type { ByteSource } from './types.js';
+/**
+ * A positional reader with a lifetime. A real `fs.promises.FileHandle` satisfies this.
+ *
+ * Structural on purpose, so `@types/node` never enters the published `.d.ts` and so a test double
+ * — or a handle from another runtime with the same API — is usable without a cast.
+ */
+export interface FileHandleLike {
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    close(): Promise<void>;
+}
+/**
+ * A `ByteSource` over an open file handle.
+ *
+ * `byteLength` is supplied by the caller rather than read from the handle, because the two ways
+ * of learning it differ in what they promise: `fileSource` takes it from the handle it just
+ * opened, while a caller wrapping a handle it already had may know something better (a range it
+ * intends to expose, a size it verified). Neither is guessed here.
+ *
+ * `close()` closes the handle. edfcore has no other lifetime mechanism in v0.1 —
+ * `Symbol.asyncDispose` is not Baseline yet — so a caller that opened a file is the one that
+ * closes it.
+ */
+export declare function fileHandleSource(handle: FileHandleLike, byteLength: number): ByteSource;
+/**
+ * Open a file for reading and expose it as a `ByteSource`.
+ *
+ * The size comes from the handle rather than from a separate `stat(path)` call, so the size and
+ * the bytes describe the same file even if the path is replaced between the two — on a rotating
+ * log or a rsync target that is not hypothetical.
+ *
+ * The handle is closed if anything goes wrong before it has an owner; after that, closing is the
+ * caller's job through `source.close()`.
+ */
+export declare function fileSource(path: string): Promise<ByteSource>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CACF,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CA0BvF;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqBlE"}

package/dist/node.js

@@ -0,0 +1,109 @@
+/**
+ * The Node adapters — the ONLY module in edfcore that imports anything from `node:`.
+ *
+ * Layer 7, published as `edfcore/node`. Keeping the import in exactly one file is what lets the
+ * universal entry (`edfcore`) be bundled for a browser without a polyfill and without a
+ * resolution alias, and a packaging test greps the built universal bundle for `node:` to prove it.
+ *
+ * Two decisions are load-bearing.
+ *
+ * 1. Reads are POSITIONAL and LOOP. `FileHandle.read` is allowed to return fewer bytes than asked
+ *    — a signal interrupted the syscall, the file lives on a network mount — and a `ByteSource`
+ *    that passed a short buffer on would be indistinguishable from a truncated file. The loop
+ *    runs until `length` bytes have arrived; a genuine end of file falls out as an
+ *    `EdfSourceError` naming both counts.
+ * 2. `fs.openAsBlob` is NEVER used, however tempting `blobSource(await openAsBlob(path))` looks.
+ *    It reports `size` modulo 2**32 and yields zeros above 4 GiB, which turns a 13 GB BDF into a
+ *    file that reads as silence with no error anywhere.
+ *
+ * TYPING. `src/` compiles with `types: []`, so `@types/node` is not available and must never be:
+ * the published `.d.ts` may not reference it, or every consumer inherits a dependency on it. The
+ * import below is therefore UNTYPED, and the minimal structural shape edfcore needs is declared
+ * here instead — `FileHandleLike` and `NodeFsPromises`. A standing CI job compiles a consumer
+ * against the real `@types/node` and asserts `fs.promises.FileHandle` is still assignable, which
+ * is what stops the two drifting.
+ *
+ * The suppression on the import is the unconditional `ts-ignore` directive rather than
+ * `@ts-expect-error`, and that is not laziness. Whether the specifier resolves depends on whether
+ * a `@types/node` happens to be reachable at all: `tsconfig.build.json` compiles `src/` alone and
+ * it is not, while `tsconfig.json` also pulls in a dev tool carrying a triple-slash reference to
+ * it and it may be. `@ts-expect-error` errors for being UNUSED in the second case, so it would
+ * break whichever of the two configurations the machine happens to disagree with.
+ */
+// biome-ignore lint/suspicious/noTsIgnore: @ts-expect-error errors when unused — see above.
+// @ts-ignore 'node:fs/promises' has no declarations under `types: []`; its shape is below.
+import * as nodeFsPromises from 'node:fs/promises';
+import { EdfSourceError } from './errors.js';
+import { assertExactRead, assertReadRange, throwIfAborted } from './io/source.js';
+const fs = nodeFsPromises;
+/**
+ * A `ByteSource` over an open file handle.
+ *
+ * `byteLength` is supplied by the caller rather than read from the handle, because the two ways
+ * of learning it differ in what they promise: `fileSource` takes it from the handle it just
+ * opened, while a caller wrapping a handle it already had may know something better (a range it
+ * intends to expose, a size it verified). Neither is guessed here.
+ *
+ * `close()` closes the handle. edfcore has no other lifetime mechanism in v0.1 —
+ * `Symbol.asyncDispose` is not Baseline yet — so a caller that opened a file is the one that
+ * closes it.
+ */
+export function fileHandleSource(handle, byteLength) {
+    return {
+        byteLength,
+        async read(offset, length, options) {
+            throwIfAborted(options);
+            assertReadRange(offset, length, byteLength);
+            if (length === 0)
+                return new Uint8Array(0);
+            const buffer = new Uint8Array(length);
+            let filled = 0;
+            while (filled < length) {
+                throwIfAborted(options);
+                // Positional: the handle's own file position is never used, so concurrent reads through
+                // one handle cannot interleave into each other's buffers.
+                const { bytesRead } = await handle.read(buffer, filled, length - filled, offset + filled);
+                // Zero bytes means end of file. Looping again would spin forever on a file that is
+                // shorter than `byteLength` claimed, so the short read is reported instead.
+                if (bytesRead <= 0)
+                    break;
+                filled += bytesRead;
+            }
+            return assertExactRead(buffer.subarray(0, filled), offset, length);
+        },
+        async close() {
+            await handle.close();
+        },
+    };
+}
+/**
+ * Open a file for reading and expose it as a `ByteSource`.
+ *
+ * The size comes from the handle rather than from a separate `stat(path)` call, so the size and
+ * the bytes describe the same file even if the path is replaced between the two — on a rotating
+ * log or a rsync target that is not hypothetical.
+ *
+ * The handle is closed if anything goes wrong before it has an owner; after that, closing is the
+ * caller's job through `source.close()`.
+ */
+export async function fileSource(path) {
+    const handle = await fs.open(path, 'r');
+    try {
+        const stats = await handle.stat();
+        const byteLength = stats.size;
+        if (!Number.isSafeInteger(byteLength) || byteLength < 0) {
+            throw new EdfSourceError(`fileSource(): the operating system reported a size of ${byteLength} bytes for ` +
+                `${JSON.stringify(path)}, which is not a byte count edfcore can address. Next: check ` +
+                'that the path names a regular file rather than a directory, a pipe or a device.', { offset: 0, requestedLength: 0 });
+        }
+        return fileHandleSource(handle, byteLength);
+    }
+    catch (error) {
+        // A failure to close is not what the caller needs to hear about: the reason the file is
+        // unusable is `error`, and letting close() replace it would hide the diagnosis behind the
+        // cleanup. The descriptor is leaked in that case, which is the lesser of the two.
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4FAA4F;AAC5F,2FAA2F;AAC3F,OAAO,KAAK,cAAc,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA2BlF,MAAM,EAAE,GAAmB,cAA2C,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAsB,EAAE,UAAkB;IACzE,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,IAAI,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;YAE3C,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,OAAO,MAAM,GAAG,MAAM,EAAE,CAAC;gBACvB,cAAc,CAAC,OAAO,CAAC,CAAC;gBACxB,wFAAwF;gBACxF,0DAA0D;gBAC1D,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;gBAC1F,mFAAmF;gBACnF,4EAA4E;gBAC5E,IAAI,SAAS,IAAI,CAAC;oBAAE,MAAM;gBAC1B,MAAM,IAAI,SAAS,CAAC;YACtB,CAAC;YACD,OAAO,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACrE,CAAC;QACD,KAAK,CAAC,KAAK;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,cAAc,CACtB,yDAAyD,UAAU,aAAa;gBAC9E,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,+DAA+D;gBACtF,iFAAiF,EACnF,EAAE,MAAM,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,CAClC,CAAC;QACJ,CAAC;QACD,OAAO,gBAAgB,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,wFAAwF;QACxF,0FAA0F;QAC1F,kFAAkF;QAClF,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/record-index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The record index: two probes at open, one targeted probe on demand, a full scan only if asked.
+ *
+ * Layer 6. This module owns the I/O STRATEGY for record onsets and nothing else — what a valid
+ * timeline is belongs to `time/timeline.ts`, what a timekeeping TAL is belongs to
+ * `tal/annotations.ts`, and segmentation belongs to `time/segments.ts`. Every onset that reaches
+ * those modules from here came out of `decodeAnnotations`, so the "first TAL of the first
+ * annotation signal" rule has exactly one implementation.
+ *
+ * Cost is the design constraint. Opening a million-record EDF+D over HTTP must not read the file,
+ * so:
+ *
+ * - a file with no annotation signal is probed ZERO times: without a timekeeping TAL there is no
+ *   per-record onset on disk, and record `r` starts at `r * recordDuration` by definition;
+ * - otherwise `buildTimeline` probes exactly two records, the first and the last, which detects
+ *   any NET drift of the timeline for two reads. It is not a proof of contiguity, and
+ *   `time/timeline.ts` says so in the diagnostic it emits;
+ * - `onsetTicks(r)` reads that ONE record and memoises the answer, so `locate()` costs
+ *   O(log recordCount) reads and a second `locate()` nearby costs almost none;
+ * - `buildRecordIndex()` is the only function here that touches every record, it is chunked so
+ *   memory stays bounded whatever the file size, and it is never called implicitly.
+ *
+ * A probe reads a whole data record rather than just the annotation signal's region. That is
+ * decision 7 of the design — the unit of I/O is the record range, never the channel range — and
+ * it is also what lets `decodeAnnotations` own the timekeeping rule: it requires the record's
+ * full bytes, and reading less would mean reimplementing that rule here.
+ */
+import type { BuildIndexOptions, ByteSource, EdfHeader, EdfRecordIndex, EdfRecording, EdfTimeline, OpenOptions } from './types.js';
+/** Records per chunk of a full traversal: bounded memory, and never fewer than one record. */
+export declare function scanChunkRecords(header: EdfHeader, maxMaterializeBytes?: number): number;
+/**
+ * The timeline and a lazily probing index, for two reads at most.
+ *
+ * The probes are records 0 and `recordCount - 1` (one probe for a single-record file, none at all
+ * when the file has no annotation signal). Both are memoised into the index, so `onsetTicks(0)`
+ * and `onsetTicks(recordCount - 1)` are free after `openEdf`.
+ *
+ * `index.coverage` stays `'probed'` and `index.segments`/`index.gaps` stay `undefined` until
+ * `buildRecordIndex()` promotes them. Nothing on the returned object can be mistaken for a
+ * verified statement that the recording is continuous.
+ */
+export declare function buildTimeline(source: ByteSource, header: EdfHeader, options?: OpenOptions): Promise<{
+    timeline: EdfTimeline;
+    index: EdfRecordIndex;
+}>;
+/**
+ * A `'complete'` index: every onset verified, with the segments and gaps they imply.
+ *
+ * This is one of only two functions that read the whole file, the other being `validateRecording`, and it is never called
+ * implicitly. Its diagnostics are deliberately not returned — an `EdfRecordIndex` is a
+ * structural answer, and `validateRecording()` is the call that reports on a traversal — but a
+ * non-monotonic timeline still throws, because no index over it would mean anything.
+ *
+ * `EdfRecording` is a plain struct, so the returned index is used by rebuilding one:
+ * `readWindow({ ...recording, index }, selection)`.
+ */
+export declare function buildRecordIndex(recording: EdfRecording, options?: BuildIndexOptions): Promise<EdfRecordIndex>;
+//# sourceMappingURL=record-index.d.ts.map

package/dist/record-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.d.ts","sourceRoot":"","sources":["../src/record-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EAIV,SAAS,EAET,cAAc,EACd,YAAY,EAEZ,WAAW,EACX,WAAW,EAGZ,MAAM,YAAY,CAAC;AAWpB,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAOxF;AAkKD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC,CAsD3D;AA4CD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,YAAY,EACvB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAyBzB"}