edfcore 0.1.0

package/src/io/cached.ts

@@ -0,0 +1,136 @@
+/**
+ * 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, ReadOptions } from '../types.js';
+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: ByteSource): ByteSource {
+  return {
+    byteLength: source.byteLength,
+    async read(offset: number, length: number, options?: ReadOptions): Promise<Uint8Array> {
+      return assertExactRead(await source.read(offset, length, options), offset, length);
+    },
+    async close(): Promise<void> {
+      await source.close?.();
+    },
+  };
+}
+
+export function cachedSource(source: ByteSource, options?: CacheOptions): ByteSource {
+  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<number, Uint8Array>();
+  const inflight = new Map<number, Promise<Uint8Array>>();
+  let cachedBytes = 0;
+
+  function evict(): void {
+    // 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: number, block: Uint8Array): void {
+    if (blocks.has(index)) return;
+    blocks.set(index, block);
+    cachedBytes += block.byteLength;
+    evict();
+  }
+
+  async function fetchBlock(index: number, options?: ReadOptions): Promise<Uint8Array> {
+    const start = index * blockBytes;
+    const length = Math.min(blockBytes, byteLength - start);
+    return assertExactRead(await source.read(start, length, options), start, length);
+  }
+
+  function blockFor(index: number, options?: ReadOptions): Promise<Uint8Array> {
+    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: number, length: number, options?: ReadOptions): Promise<Uint8Array> {
+      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: Array<Promise<Uint8Array>> = [];
+      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(): Promise<void> {
+      blocks.clear();
+      inflight.clear();
+      cachedBytes = 0;
+      await source.close?.();
+    },
+  };
+}

package/src/io/http.ts

@@ -0,0 +1,299 @@
+/**
+ * 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 type {
+  AbortSignalLike,
+  ByteSource,
+  FetchLike,
+  HttpResponseLike,
+  HttpSourceOptions,
+  ReadOptions,
+} from '../types.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;
+
+type RequestInitLike = { headers: Record<string, string>; method?: string };
+
+/**
+ * A promise semaphore. A released slot is handed straight to the next waiter rather than being
+ * returned to the pool, so the in-flight count can never overshoot the limit between the
+ * release and the waiter resuming on its microtask.
+ */
+interface Gate {
+  acquire(): Promise<void>;
+  release(): void;
+}
+
+function createGate(limit: number): Gate {
+  let active = 0;
+  const waiting: Array<() => void> = [];
+
+  return {
+    async acquire(): Promise<void> {
+      if (active < limit) {
+        active += 1;
+        return;
+      }
+      await new Promise<void>((resolve) => {
+        waiting.push(resolve);
+      });
+      // The releaser transferred its slot to us, so `active` is deliberately left unchanged.
+    },
+    release(): void {
+      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: HttpResponseLike, name: string): string | null {
+  return response.headers.get(name) ?? response.headers.get(name.toLowerCase());
+}
+
+function parseNonNegativeInteger(text: string | null): number | undefined {
+  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: string | null): number | undefined {
+  if (value === null) return undefined;
+  const slash = value.lastIndexOf('/');
+  if (slash < 0) return undefined;
+  return parseNonNegativeInteger(value.slice(slash + 1));
+}
+
+function isSuccess(status: number): boolean {
+  return status >= 200 && status < 300;
+}
+
+function hrefOf(url: string | { readonly href: string }): string {
+  return typeof url === 'string' ? url : url.href;
+}
+
+function resolveFetch(options: HttpSourceOptions | undefined): FetchLike {
+  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 as { fetch?: FetchLike }).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: RequestInitLike, signal: AbortSignalLike | undefined): void {
+  if (signal === undefined) return;
+  if (typeof (signal as { addEventListener?: unknown }).addEventListener !== 'function') return;
+  (init as { signal?: unknown }).signal = signal;
+}
+
+function request(
+  fetchImpl: FetchLike,
+  href: string,
+  headers: Record<string, string>,
+  method: 'GET' | 'HEAD',
+  signal: AbortSignalLike | undefined,
+): Promise<HttpResponseLike> {
+  const init: RequestInitLike = { headers, method };
+  attachSignal(init, signal);
+  return fetchImpl(href, init);
+}
+
+function rangeIgnoredError(href: string, offset: number, length: number): EdfSourceError {
+  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 },
+  );
+}
+
+/** What `httpSource` learns before it can serve a single read. */
+interface ResolvedSource {
+  readonly byteLength: number;
+  /** Set only when the length probe already had to download everything. */
+  readonly body: Uint8Array | undefined;
+}
+
+async function resolveSource(
+  fetchImpl: FetchLike,
+  href: string,
+  baseHeaders: Record<string, string>,
+  options: HttpSourceOptions | undefined,
+): Promise<ResolvedSource> {
+  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: string | { readonly href: string },
+  options?: HttpSourceOptions,
+): Promise<ByteSource> {
+  const href = hrefOf(url);
+  const fetchImpl = resolveFetch(options);
+  const baseHeaders: Record<string, string> = { ...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: Uint8Array | undefined = resolved.body;
+
+  async function fetchRange(
+    offset: number,
+    length: number,
+    readOptions: ReadOptions | undefined,
+  ): Promise<Uint8Array> {
+    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: number, length: number, readOptions?: ReadOptions): Promise<Uint8Array> {
+      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: Uint8Array, offset: number, length: number): Uint8Array {
+  return assertExactRead(body.slice(offset, offset + length), offset, length);
+}

package/src/io/read.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 type { ByteSource, EdfHeader, OpenOptions, ReadOptions, RecordRange } from '../types.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: Uint8Array): number | undefined {
+  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: ByteSource, options?: OpenOptions): Promise<EdfHeader> {
+  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: RecordRange): string {
+  return `{ start: ${range.start}, count: ${range.count} }`;
+}
+
+function assertRecordRange(header: EdfHeader, records: RecordRange): void {
+  const available: RecordRange = { 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: number,
+  records: RecordRange,
+  options?: ReadOptions,
+): void {
+  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: ByteSource,
+  header: EdfHeader,
+  records: RecordRange,
+  options?: ReadOptions,
+): Promise<Uint8Array> {
+  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,
+  );
+}

package/src/io/source.ts

@@ -0,0 +1,87 @@
+/**
+ * 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';
+import type { ReadOptions } from '../types.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: unknown): number | undefined {
+  if (received === null || received === undefined) return undefined;
+  const length = (received as { length?: unknown }).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: Uint8Array, offset: number, length: number): Uint8Array {
+  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: number, length: number, byteLength: number): void {
+  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?: ReadOptions): void {
+  if (options?.signal?.aborted !== true) return;
+  const error = new Error('The read was aborted through options.signal.');
+  error.name = 'AbortError';
+  throw error;
+}