edfcore 0.1.0

package/dist/io/blob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob.js","sourceRoot":"","sources":["../../src/io/blob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/E,MAAM,UAAU,UAAU,CAAC,IAAc;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC;IAE7B,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;YAC3C,kEAAkE;YAClE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;YACvE,cAAc,CAAC,OAAO,CAAC,CAAC;YACxB,OAAO,eAAe,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/io/bytes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The in-memory adapter.
+ *
+ * Layer 5. Zero-copy by construction: a read hands back a `subarray` view over the caller's own
+ * buffer. That is safe precisely because it is the caller's buffer — the "returned array is
+ * owned by the caller" rule exists to stop an adapter handing out a view into state it retains,
+ * and this adapter retains nothing the caller does not already hold.
+ */
+import type { ByteSource } from '../types.js';
+export declare function byteSource(bytes: ArrayBuffer | Uint8Array): ByteSource;
+//# sourceMappingURL=bytes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/io/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAG3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,CAgBtE"}

package/dist/io/bytes.js

@@ -0,0 +1,26 @@
+/**
+ * The in-memory adapter.
+ *
+ * Layer 5. Zero-copy by construction: a read hands back a `subarray` view over the caller's own
+ * buffer. That is safe precisely because it is the caller's buffer — the "returned array is
+ * owned by the caller" rule exists to stop an adapter handing out a view into state it retains,
+ * and this adapter retains nothing the caller does not already hold.
+ */
+import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+export function byteSource(bytes) {
+    // `ArrayBuffer.isView` rather than `instanceof Uint8Array`: `instanceof` is false for a view
+    // that crossed a realm boundary (a worker, an iframe), and this is a public entry point.
+    const view = ArrayBuffer.isView(bytes) ? bytes : new Uint8Array(bytes);
+    const byteLength = view.byteLength;
+    return {
+        byteLength,
+        async read(offset, length, options) {
+            throwIfAborted(options);
+            assertReadRange(offset, length, byteLength);
+            // `subarray` is relative to this view, so a Uint8Array handed in with a non-zero
+            // byteOffset over a larger buffer is respected with no offset arithmetic here.
+            return assertExactRead(view.subarray(offset, offset + length), offset, length);
+        },
+    };
+}
+//# sourceMappingURL=bytes.js.map

package/dist/io/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../src/io/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/E,MAAM,UAAU,UAAU,CAAC,KAA+B;IACxD,6FAA6F;IAC7F,yFAAyF;IACzF,MAAM,IAAI,GAAe,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACnF,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAEnC,OAAO;QACL,UAAU;QACV,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,MAAc,EAAE,OAAqB;YAC9D,cAAc,CAAC,OAAO,CAAC,CAAC;YACxB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YAC5C,iFAAiF;YACjF,+EAA+E;YAC/E,OAAO,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACjF,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/io/cached.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The only cache in edfcore: opt-in, visible at the call site, and removed by deleting one
+ * wrapper from the expression that built the source.
+ *
+ * Layer 5. A block-aligned LRU over an arbitrary `ByteSource`. Two properties matter more than
+ * the hit rate:
+ *
+ * 1. A read returns a COPY, never a view into a retained block. `types.ts` gives the returned
+ *    array to the caller, and a caller who writes into it must not be able to corrupt what the
+ *    next reader sees.
+ * 2. Concurrent reads wanting the same block issue ONE underlying read. Over HTTP the
+ *    difference between one request and eight is the difference between usable and not.
+ *
+ * Block boundaries are byte-aligned, not record-aligned: this module is format-independent by
+ * construction and has no access to a header, so there is no record size to align to.
+ */
+import type { ByteSource, CacheOptions } from '../types.js';
+export declare function cachedSource(source: ByteSource, options?: CacheOptions): ByteSource;
+//# sourceMappingURL=cached.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cached.d.ts","sourceRoot":"","sources":["../../src/io/cached.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAe,MAAM,aAAa,CAAC;AAmBzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,UAAU,CAmGnF"}

package/dist/io/cached.js

@@ -0,0 +1,129 @@
+/**
+ * The only cache in edfcore: opt-in, visible at the call site, and removed by deleting one
+ * wrapper from the expression that built the source.
+ *
+ * Layer 5. A block-aligned LRU over an arbitrary `ByteSource`. Two properties matter more than
+ * the hit rate:
+ *
+ * 1. A read returns a COPY, never a view into a retained block. `types.ts` gives the returned
+ *    array to the caller, and a caller who writes into it must not be able to corrupt what the
+ *    next reader sees.
+ * 2. Concurrent reads wanting the same block issue ONE underlying read. Over HTTP the
+ *    difference between one request and eight is the difference between usable and not.
+ *
+ * Block boundaries are byte-aligned, not record-aligned: this module is format-independent by
+ * construction and has no access to a header, so there is no record size to align to.
+ */
+import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+const DEFAULT_BLOCK_BYTES = 1024 * 1024;
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+/** Delegation with the contract still enforced, for configurations that cannot cache. */
+function passThrough(source) {
+    return {
+        byteLength: source.byteLength,
+        async read(offset, length, options) {
+            return assertExactRead(await source.read(offset, length, options), offset, length);
+        },
+        async close() {
+            await source.close?.();
+        },
+    };
+}
+export function cachedSource(source, options) {
+    const byteLength = source.byteLength;
+    const maxBytes = Math.max(0, Math.floor(options?.maxBytes ?? DEFAULT_MAX_BYTES));
+    const requestedBlockBytes = Math.max(1, Math.floor(options?.blockBytes ?? DEFAULT_BLOCK_BYTES));
+    // A block wider than the whole budget would evict itself on every insert, so the block is
+    // clamped to the budget rather than the cache being left in a state that can never hold one.
+    const blockBytes = Math.min(requestedBlockBytes, maxBytes);
+    if (blockBytes < 1)
+        return passThrough(source);
+    /** Insertion order is LRU order, oldest first; a hit re-inserts to move to the back. */
+    const blocks = new Map();
+    const inflight = new Map();
+    let cachedBytes = 0;
+    function evict() {
+        // Deleting during Map iteration is well defined and never revisits an entry, so this walks
+        // strictly from the oldest block forward.
+        for (const [index, block] of blocks) {
+            if (cachedBytes <= maxBytes)
+                return;
+            blocks.delete(index);
+            cachedBytes -= block.byteLength;
+        }
+    }
+    function admit(index, block) {
+        if (blocks.has(index))
+            return;
+        blocks.set(index, block);
+        cachedBytes += block.byteLength;
+        evict();
+    }
+    async function fetchBlock(index, options) {
+        const start = index * blockBytes;
+        const length = Math.min(blockBytes, byteLength - start);
+        return assertExactRead(await source.read(start, length, options), start, length);
+    }
+    function blockFor(index, options) {
+        const cached = blocks.get(index);
+        if (cached !== undefined) {
+            blocks.delete(index);
+            blocks.set(index, cached);
+            return Promise.resolve(cached);
+        }
+        const pending = inflight.get(index);
+        // Deduped readers share the first caller's options, which is inherent to issuing one read
+        // for all of them.
+        if (pending !== undefined)
+            return pending;
+        const started = fetchBlock(index, options)
+            .then((block) => {
+            admit(index, block);
+            return block;
+        })
+            .finally(() => {
+            inflight.delete(index);
+        });
+        inflight.set(index, started);
+        return started;
+    }
+    return {
+        byteLength,
+        async read(offset, length, options) {
+            throwIfAborted(options);
+            assertReadRange(offset, length, byteLength);
+            if (length === 0)
+                return new Uint8Array(0);
+            // A read wider than the entire budget cannot benefit from the cache and would evict every
+            // block on its way through, so it goes straight to the source.
+            if (length > maxBytes) {
+                return assertExactRead(await source.read(offset, length, options), offset, length);
+            }
+            const firstBlock = Math.floor(offset / blockBytes);
+            const lastBlock = Math.floor((offset + length - 1) / blockBytes);
+            const pending = [];
+            for (let index = firstBlock; index <= lastBlock; index += 1) {
+                pending.push(blockFor(index, options));
+            }
+            const resolved = await Promise.all(pending);
+            throwIfAborted(options);
+            const out = new Uint8Array(length);
+            for (const [position, block] of resolved.entries()) {
+                const blockStart = (firstBlock + position) * blockBytes;
+                const from = Math.max(offset, blockStart);
+                const to = Math.min(offset + length, blockStart + block.byteLength);
+                if (to <= from)
+                    continue;
+                out.set(block.subarray(from - blockStart, to - blockStart), from - offset);
+            }
+            return assertExactRead(out, offset, length);
+        },
+        async close() {
+            blocks.clear();
+            inflight.clear();
+            cachedBytes = 0;
+            await source.close?.();
+        },
+    };
+}
+//# sourceMappingURL=cached.js.map

package/dist/io/cached.js.map

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

package/dist/io/http.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The HTTP Range adapter.
+ *
+ * Layer 5. Turns a URL into random access without downloading the recording, which is the
+ * whole reason a 13 GiB BDF can be opened in a browser tab.
+ *
+ * Three things here are load-bearing and easy to get wrong:
+ *
+ * 1. A byte range is INCLUSIVE at both ends. `bytes=0-0` is one byte.
+ * 2. A `200 OK` answer to a Range request means the server ignored the header and is sending
+ *    the whole resource. That is refused by default — silently buffering gigabytes because a
+ *    CDN is misconfigured is exactly the kind of invisible cost this library exists to refuse.
+ * 3. The source length must be known before any read, because random access is meaningless
+ *    without it. Three ways are tried, cheapest first, and failing to find one is fatal.
+ */
+import type { ByteSource, HttpSourceOptions } from '../types.js';
+export declare function httpSource(url: string | {
+    readonly href: string;
+}, options?: HttpSourceOptions): Promise<ByteSource>;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/io/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAEV,UAAU,EAGV,iBAAiB,EAElB,MAAM,aAAa,CAAC;AA0MrB,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACvC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAgErB"}

package/dist/io/http.js

@@ -0,0 +1,225 @@
+/**
+ * The HTTP Range adapter.
+ *
+ * Layer 5. Turns a URL into random access without downloading the recording, which is the
+ * whole reason a 13 GiB BDF can be opened in a browser tab.
+ *
+ * Three things here are load-bearing and easy to get wrong:
+ *
+ * 1. A byte range is INCLUSIVE at both ends. `bytes=0-0` is one byte.
+ * 2. A `200 OK` answer to a Range request means the server ignored the header and is sending
+ *    the whole resource. That is refused by default — silently buffering gigabytes because a
+ *    CDN is misconfigured is exactly the kind of invisible cost this library exists to refuse.
+ * 3. The source length must be known before any read, because random access is meaningless
+ *    without it. Three ways are tried, cheapest first, and failing to find one is fatal.
+ */
+import { EdfSourceError } from '../errors.js';
+import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+/** Small enough to stay polite to a shared origin, large enough to hide latency. */
+const DEFAULT_MAX_CONCURRENCY = 4;
+const HTTP_PARTIAL_CONTENT = 206;
+const HTTP_OK = 200;
+function createGate(limit) {
+    let active = 0;
+    const waiting = [];
+    return {
+        async acquire() {
+            if (active < limit) {
+                active += 1;
+                return;
+            }
+            await new Promise((resolve) => {
+                waiting.push(resolve);
+            });
+            // The releaser transferred its slot to us, so `active` is deliberately left unchanged.
+        },
+        release() {
+            const next = waiting.shift();
+            if (next !== undefined) {
+                next();
+                return;
+            }
+            active -= 1;
+        },
+    };
+}
+/**
+ * A real `Headers` lookup is case-insensitive, but `HttpResponseLike` is structural and a
+ * hand-written test double usually is not. Both spellings are tried.
+ */
+function headerOf(response, name) {
+    return response.headers.get(name) ?? response.headers.get(name.toLowerCase());
+}
+function parseNonNegativeInteger(text) {
+    if (text === null)
+        return undefined;
+    const trimmed = text.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    const value = Number(trimmed);
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+/** `Content-Range: bytes 0-0/12345` -> 12345. A `/*` total is unknown, not zero. */
+function totalFromContentRange(value) {
+    if (value === null)
+        return undefined;
+    const slash = value.lastIndexOf('/');
+    if (slash < 0)
+        return undefined;
+    return parseNonNegativeInteger(value.slice(slash + 1));
+}
+function isSuccess(status) {
+    return status >= 200 && status < 300;
+}
+function hrefOf(url) {
+    return typeof url === 'string' ? url : url.href;
+}
+function resolveFetch(options) {
+    const provided = options?.fetch;
+    if (provided !== undefined)
+        return provided;
+    // `fetch` cannot be named as a global without the DOM lib, so it is reached structurally.
+    const ambient = globalThis.fetch;
+    if (ambient !== undefined)
+        return ambient;
+    throw new EdfSourceError('httpSource() found no fetch implementation: this runtime does not expose globalThis.fetch ' +
+        'and options.fetch was not given. Next: pass options.fetch with any function matching ' +
+        'FetchLike.', { offset: 0, requestedLength: 0 });
+}
+/**
+ * `FetchLike` deliberately does not name `signal`: naming it would pull in the real DOM
+ * `AbortSignal` by parameter contravariance, the exact dependency the shims exist to avoid. It
+ * is still handed to the implementation at runtime.
+ *
+ * It is attached only when it carries `addEventListener`, i.e. when it genuinely is an
+ * `AbortSignal`. The platform `fetch` throws a `TypeError` on anything else, and a caller who
+ * passed a bare `{ aborted }` shim is still served by the `throwIfAborted` polls around the
+ * request.
+ */
+function attachSignal(init, signal) {
+    if (signal === undefined)
+        return;
+    if (typeof signal.addEventListener !== 'function')
+        return;
+    init.signal = signal;
+}
+function request(fetchImpl, href, headers, method, signal) {
+    const init = { headers, method };
+    attachSignal(init, signal);
+    return fetchImpl(href, init);
+}
+function rangeIgnoredError(href, offset, length) {
+    const lastByte = offset + length - 1;
+    return new EdfSourceError(`The server answered ${HTTP_OK} OK instead of ${HTTP_PARTIAL_CONTENT} Partial Content for ` +
+        `Range bytes=${offset}-${lastByte} on ${href}, so it ignored the Range header and is ` +
+        'sending the whole resource (HTTP_RANGE_IGNORED). edfcore will not silently buffer a ' +
+        'recording nobody asked for. Next: serve the file from an origin or CDN that supports ' +
+        'byte ranges, or pass allowFullDownload: true to fetch it once and serve reads from ' +
+        'memory.', { offset, requestedLength: length });
+}
+async function resolveSource(fetchImpl, href, baseHeaders, options) {
+    const signal = options?.signal;
+    const declared = options?.byteLength;
+    if (declared !== undefined) {
+        if (!Number.isSafeInteger(declared) || declared < 0) {
+            throw new EdfSourceError(`httpSource() was given options.byteLength ${declared}, which is not a non-negative ` +
+                'safe integer. Next: pass the real resource size in bytes, or omit it and let ' +
+                'edfcore probe for it.', { offset: 0, requestedLength: 0 });
+        }
+        return { byteLength: declared, body: undefined };
+    }
+    try {
+        const head = await request(fetchImpl, href, baseHeaders, 'HEAD', signal);
+        if (isSuccess(head.status)) {
+            const length = parseNonNegativeInteger(headerOf(head, 'Content-Length'));
+            if (length !== undefined)
+                return { byteLength: length, body: undefined };
+        }
+    }
+    catch {
+        // A rejected or forbidden HEAD is common (CORS, some object stores). Fall through to the
+        // one-byte range probe rather than failing on it.
+    }
+    const probeHeaders = { ...baseHeaders, Range: 'bytes=0-0' };
+    const probe = await request(fetchImpl, href, probeHeaders, 'GET', signal);
+    if (probe.status === HTTP_PARTIAL_CONTENT) {
+        const total = totalFromContentRange(headerOf(probe, 'Content-Range'));
+        if (total !== undefined)
+            return { byteLength: total, body: undefined };
+    }
+    else if (probe.status === HTTP_OK) {
+        // The probe already committed the server to sending everything. Refusing now costs the
+        // caller nothing, and accepting means one download instead of two.
+        if (options?.allowFullDownload !== true)
+            throw rangeIgnoredError(href, 0, 1);
+        const body = new Uint8Array(await probe.arrayBuffer());
+        return { byteLength: body.byteLength, body };
+    }
+    else if (!isSuccess(probe.status)) {
+        throw new EdfSourceError(`httpSource() could not read ${href}: the server answered HTTP ${probe.status} to a ` +
+            'Range probe. Next: check the URL, its authentication headers and its CORS policy.', { offset: 0, requestedLength: 1 });
+    }
+    throw new EdfSourceError(`httpSource() could not determine the size of ${href}: HEAD returned no usable ` +
+        'Content-Length and a Range probe returned no Content-Range total, so no byte offset can ' +
+        'be addressed and random access is impossible. Next: pass options.byteLength if you know ' +
+        'the size, or serve the file from an origin that reports one.', { offset: 0, requestedLength: 0 });
+}
+export async function httpSource(url, options) {
+    const href = hrefOf(url);
+    const fetchImpl = resolveFetch(options);
+    const baseHeaders = { ...options?.headers };
+    const gate = createGate(Math.max(1, Math.floor(options?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY)));
+    const resolved = await resolveSource(fetchImpl, href, baseHeaders, options);
+    const byteLength = resolved.byteLength;
+    /** Set once, and only ever when the server ignored Range and the caller allowed it. */
+    let fullBody = resolved.body;
+    async function fetchRange(offset, length, readOptions) {
+        const signal = readOptions?.signal ?? options?.signal;
+        // INCLUSIVE end: `bytes=0-0` is one byte, so the last addressed byte is offset+length-1.
+        const headers = { ...baseHeaders, Range: `bytes=${offset}-${offset + length - 1}` };
+        await gate.acquire();
+        try {
+            throwIfAborted(readOptions);
+            const response = await request(fetchImpl, href, headers, 'GET', signal);
+            if (response.status === HTTP_PARTIAL_CONTENT) {
+                const bytes = new Uint8Array(await response.arrayBuffer());
+                return assertExactRead(bytes, offset, length);
+            }
+            if (response.status === HTTP_OK) {
+                if (options?.allowFullDownload !== true)
+                    throw rangeIgnoredError(href, offset, length);
+                const body = new Uint8Array(await response.arrayBuffer());
+                // A concurrent read may have won the race; either copy is the same resource, so keep
+                // whichever landed first and let this one be collected.
+                if (fullBody === undefined)
+                    fullBody = body;
+                return sliceFullBody(fullBody, offset, length);
+            }
+            throw new EdfSourceError(`Reading bytes ${offset}..${offset + length - 1} of ${href} failed: the server ` +
+                `answered HTTP ${response.status}. Next: check the URL, its authentication headers ` +
+                'and whether a signed URL has expired.', { offset, requestedLength: length });
+        }
+        finally {
+            gate.release();
+        }
+    }
+    return {
+        byteLength,
+        async read(offset, length, readOptions) {
+            throwIfAborted(readOptions);
+            assertReadRange(offset, length, byteLength);
+            if (length === 0)
+                return new Uint8Array(0);
+            if (fullBody !== undefined)
+                return sliceFullBody(fullBody, offset, length);
+            const bytes = await fetchRange(offset, length, readOptions);
+            throwIfAborted(readOptions);
+            return bytes;
+        },
+    };
+}
+/** `slice`, not `subarray`: the buffered body is retained state and the caller owns its result. */
+function sliceFullBody(body, offset, length) {
+    return assertExactRead(body.slice(offset, offset + length), offset, length);
+}
+//# sourceMappingURL=http.js.map

package/dist/io/http.js.map

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

package/dist/io/read.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Header prefetch and record-range translation.
+ *
+ * Layer 6. Nothing here interprets a byte: this module decides WHICH bytes to ask a `ByteSource`
+ * for, and hands them to the pure layer unchanged. Two rules are the whole file.
+ *
+ * 1. A header costs exactly TWO source reads — 256 bytes to learn the signal count, then the
+ *    remaining `256 * ns` as one range. Never one read per signal block, and never a speculative
+ *    read of a size the file has not stated.
+ * 2. The unit of I/O is the RECORD RANGE, never the channel range. `readRecordBytes` issues one
+ *    contiguous read covering every signal over the requested records, and de-interleaving
+ *    happens in memory afterwards. There is no cheap single-channel read in EDF — ten seconds of
+ *    one channel out of thirty is a 27x overread spread over ten requests, against a single
+ *    153,600-byte read for all thirty — and this API says so instead of hiding it.
+ *
+ * The exact-length contract is re-verified here even though every bundled adapter already checks
+ * it, because a `ByteSource` may be the caller's own and a silently short read is
+ * indistinguishable from a truncated file.
+ */
+import type { ByteSource, EdfHeader, OpenOptions, ReadOptions, RecordRange } from '../types.js';
+/**
+ * Parse the header of `source`, reading it in exactly two ranges.
+ *
+ * Both reads are clamped to the source length so that a file too short for the header it declares
+ * reaches `parseHeader` and is reported as `SOURCE_TOO_SMALL` — a file defect — instead of
+ * surfacing as an `EdfSourceError` about a range past the end, which would blame the source for
+ * the file's problem.
+ */
+export declare function readHeader(source: ByteSource, options?: OpenOptions): Promise<EdfHeader>;
+/**
+ * The bytes of a record range: ONE contiguous read covering every signal.
+ *
+ * The returned buffer is exactly `records.count * header.recordByteLength` bytes and begins at
+ * record `records.start`, which is precisely what `decodeDigital` and `decodeAnnotations` demand
+ * — pass it to them unsliced.
+ *
+ * A zero-record range issues no read at all. A zero-length HTTP range is not expressible (`bytes=
+ * n--1`), and there is nothing to fetch, so returning the empty buffer is both cheaper and more
+ * honest than asking for it.
+ */
+export declare function readRecordBytes(source: ByteSource, header: EdfHeader, records: RecordRange, options?: ReadOptions): Promise<Uint8Array>;
+//# sourceMappingURL=read.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/io/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAoBhG;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAwB9F;AAyCD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CAYrB"}

package/dist/io/read.js

@@ -0,0 +1,119 @@
+/**
+ * Header prefetch and record-range translation.
+ *
+ * Layer 6. Nothing here interprets a byte: this module decides WHICH bytes to ask a `ByteSource`
+ * for, and hands them to the pure layer unchanged. Two rules are the whole file.
+ *
+ * 1. A header costs exactly TWO source reads — 256 bytes to learn the signal count, then the
+ *    remaining `256 * ns` as one range. Never one read per signal block, and never a speculative
+ *    read of a size the file has not stated.
+ * 2. The unit of I/O is the RECORD RANGE, never the channel range. `readRecordBytes` issues one
+ *    contiguous read covering every signal over the requested records, and de-interleaving
+ *    happens in memory afterwards. There is no cheap single-channel read in EDF — ten seconds of
+ *    one channel out of thirty is a 27x overread spread over ten requests, against a single
+ *    153,600-byte read for all thirty — and this API says so instead of hiding it.
+ *
+ * The exact-length contract is re-verified here even though every bundled adapter already checks
+ * it, because a `ByteSource` may be the caller's own and a silently short read is
+ * indistinguishable from a truncated file.
+ */
+import { parseEdfInteger } from '../bytes/numbers.js';
+import { readAsciiField } from '../bytes/view.js';
+import { DEFAULT_MAX_MATERIALIZE_BYTES, EDF_HEADER_BLOCK_BYTES, EDF_MAX_SIGNAL_COUNT, HEADER_FIELDS, } from '../constants.js';
+import { EdfBudgetError, EdfRangeError } from '../errors.js';
+import { parseHeader } from '../header/parse.js';
+import { assertExactRead } from './source.js';
+/**
+ * The signal count, read leniently and reported to nobody.
+ *
+ * This is a PREFETCH HINT and nothing else: it decides how many bytes the second read asks for.
+ * Every judgement about the field — the 1..9999 range, the layout, which diagnostic a bad value
+ * deserves and in which order — belongs to `header/parse.ts`, which owns the pinned check order.
+ * Returning `undefined` here simply means the second read is skipped and `parseHeader` gets the
+ * 256 bytes we have, so it can produce the right error rather than this module guessing at one.
+ */
+function signalCountHint(fixedHeader) {
+    if (fixedHeader.length < EDF_HEADER_BLOCK_BYTES)
+        return undefined;
+    const { offset, length } = HEADER_FIELDS.signalCount;
+    const parse = parseEdfInteger(readAsciiField(fixedHeader, offset, length));
+    if (!parse.ok || parse.value < 1 || parse.value > EDF_MAX_SIGNAL_COUNT)
+        return undefined;
+    return parse.value;
+}
+/**
+ * Parse the header of `source`, reading it in exactly two ranges.
+ *
+ * Both reads are clamped to the source length so that a file too short for the header it declares
+ * reaches `parseHeader` and is reported as `SOURCE_TOO_SMALL` — a file defect — instead of
+ * surfacing as an `EdfSourceError` about a range past the end, which would blame the source for
+ * the file's problem.
+ */
+export async function readHeader(source, options) {
+    const sourceByteLength = source.byteLength;
+    const firstLength = Math.min(EDF_HEADER_BLOCK_BYTES, sourceByteLength);
+    const fixedHeader = assertExactRead(await source.read(0, firstLength, options), 0, firstLength);
+    const signalCount = signalCountHint(fixedHeader);
+    if (signalCount === undefined)
+        return parseHeader(fixedHeader, sourceByteLength, options);
+    const headerByteLength = EDF_HEADER_BLOCK_BYTES * (signalCount + 1);
+    const remaining = Math.min(headerByteLength, sourceByteLength) - firstLength;
+    if (remaining <= 0)
+        return parseHeader(fixedHeader, sourceByteLength, options);
+    const rest = assertExactRead(await source.read(firstLength, remaining, options), firstLength, remaining);
+    // One contiguous buffer, because `parseHeader` addresses per-signal fields by absolute offset.
+    // At most 256 * 10000 bytes, so this allocation needs no budget of its own.
+    const headerBytes = new Uint8Array(firstLength + remaining);
+    headerBytes.set(fixedHeader, 0);
+    headerBytes.set(rest, firstLength);
+    return parseHeader(headerBytes, sourceByteLength, options);
+}
+function describeRange(range) {
+    return `{ start: ${range.start}, count: ${range.count} }`;
+}
+function assertRecordRange(header, records) {
+    const available = { start: 0, count: header.recordCount };
+    const startValid = Number.isSafeInteger(records.start) && records.start >= 0;
+    const countValid = Number.isSafeInteger(records.count) && records.count >= 0;
+    if (startValid && countValid && records.start + records.count <= header.recordCount)
+        return;
+    throw new EdfRangeError(`readRecordBytes(): records ${describeRange(records)} is not inside the ` +
+        `${header.recordCount} data records this file contains. Next: clamp the range against ` +
+        'header.recordCount, or call index.locate(seconds) to find a record index for a time.', { requested: records, available });
+}
+/**
+ * Refused BEFORE the allocation, never during it.
+ *
+ * A record range is the one read in edfcore whose size the caller controls directly, so it is the
+ * one that can take a browser tab down by honest arithmetic. A typed error naming both numbers
+ * beats an out-of-memory crash with no attribution.
+ */
+function assertWithinBudget(requiredBytes, records, options) {
+    const budgetBytes = options?.maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES;
+    if (requiredBytes <= budgetBytes)
+        return;
+    throw new EdfBudgetError(`Reading records ${describeRange(records)} needs a ${requiredBytes}-byte buffer, above the ` +
+        `${budgetBytes}-byte maxMaterializeBytes budget, so the read was refused before anything ` +
+        'was allocated. Next: read fewer records per call, or raise options.maxMaterializeBytes.', { requiredBytes, budgetBytes });
+}
+/**
+ * The bytes of a record range: ONE contiguous read covering every signal.
+ *
+ * The returned buffer is exactly `records.count * header.recordByteLength` bytes and begins at
+ * record `records.start`, which is precisely what `decodeDigital` and `decodeAnnotations` demand
+ * — pass it to them unsliced.
+ *
+ * A zero-record range issues no read at all. A zero-length HTTP range is not expressible (`bytes=
+ * n--1`), and there is nothing to fetch, so returning the empty buffer is both cheaper and more
+ * honest than asking for it.
+ */
+export async function readRecordBytes(source, header, records, options) {
+    assertRecordRange(header, records);
+    const byteLength = records.count * header.recordByteLength;
+    if (byteLength === 0)
+        return new Uint8Array(0);
+    assertWithinBudget(byteLength, records, options);
+    const byteOffset = header.headerByteLength + records.start * header.recordByteLength;
+    return assertExactRead(await source.read(byteOffset, byteLength, options), byteOffset, byteLength);
+}
+//# sourceMappingURL=read.js.map