@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/streams/collect.js

@@ -1,26 +1,75 @@
-async function collectStream(stream) {
-  const reader = stream.getReader();
-  try {
-    const chunks = [];
-    let total = 0;
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      chunks.push(value);
-      total += value.byteLength;
-    }
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.byteLength;
-    }
-    return result;
-  } finally {
-    reader.releaseLock();
-  }
+//#region src/streams/collect.ts
+/**
+* Drain a `ReadableStream<Uint8Array>` into a single contiguous
+* `Uint8Array`. Releases the reader lock on both the happy and error
+* paths so the underlying stream can propagate close / error events to
+* the upstream producer.
+*
+* Used by both `createParallelDownloadStream` (per-range fetch) and
+* `StreamSource.toArrayBuffer` (whole-source materialisation). The two
+* code paths previously hand-rolled the same accumulate-then-concat
+* loop; consolidating here removes ~25 duplicated lines and a class of
+* lock-leak bugs.
+*
+* @param stream - Readable stream to consume. Will be fully drained.
+* @param options - Optional abort signal used to stop a pending read.
+*
+* @returns A new `Uint8Array` containing every byte the stream produced.
+*/
+async function collectStream(stream, options = {}) {
+	const reader = stream.getReader();
+	try {
+		const chunks = [];
+		let total = 0;
+		while (true) {
+			const { done, value } = await readStreamChunkWithSignal(reader, options.signal);
+			if (done) break;
+			chunks.push(value);
+			total += value.byteLength;
+		}
+		const result = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			result.set(chunk, offset);
+			offset += chunk.byteLength;
+		}
+		return result;
+	} finally {
+		reader.releaseLock();
+	}
 }
-export {
-  collectStream
-};
-//# sourceMappingURL=collect.js.map
+/**
+* Reads one chunk and rejects when the supplied signal aborts.
+* @param reader - Stream reader to read from.
+* @param signal - Optional abort signal that cancels the read.
+*
+* @returns The next stream read result.
+*
+* @internal
+*/
+async function readStreamChunkWithSignal(reader, signal) {
+	if (signal === void 0) return reader.read();
+	signal.throwIfAborted();
+	let removeAbortListener;
+	const abortPromise = new Promise((_, reject) => {
+		const onAbort = () => {
+			const reason = abortReason(signal);
+			reject(reason);
+			reader.cancel(reason).catch(() => {});
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+	});
+	try {
+		return await Promise.race([reader.read(), abortPromise]);
+	} finally {
+		removeAbortListener?.();
+	}
+}
+function abortReason(signal) {
+	return signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+}
+//#endregion
+export { collectStream, readStreamChunkWithSignal };
+
+//# sourceMappingURL=collect.js.map

package/dist/streams/collect.js.map

@@ -1 +1 @@
-{"version":3,"file":"collect.js","sources":["../../src/streams/collect.ts"],"sourcesContent":["/**\n * Drain a `ReadableStream<Uint8Array>` into a single contiguous\n * `Uint8Array`. Releases the reader lock on both the happy and error\n * paths so the underlying stream can propagate close / error events to\n * the upstream producer.\n *\n * Used by both `createParallelDownloadStream` (per-range fetch) and\n * `StreamSource.toArrayBuffer` (whole-source materialisation). The two\n * code paths previously hand-rolled the same accumulate-then-concat\n * loop; consolidating here removes ~25 duplicated lines and a class of\n * lock-leak bugs.\n *\n * @param stream - Readable stream to consume. Will be fully drained.\n *\n * @returns A new `Uint8Array` containing every byte the stream produced.\n */\nexport async function collectStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {\n  const reader = stream.getReader()\n  try {\n    const chunks: Uint8Array[] = []\n    let total = 0\n    while (true) {\n      const { done, value } = await reader.read()\n      if (done) break\n      chunks.push(value)\n      total += value.byteLength\n    }\n    const result = new Uint8Array(total)\n    let offset = 0\n    for (const chunk of chunks) {\n      result.set(chunk, offset)\n      offset += chunk.byteLength\n    }\n    return result\n  } finally {\n    // Releasing here lets the underlying stream propagate close / error\n    // events to any upstream producer (e.g. a Node `Readable`) even on\n    // the error path where a mid-read throw left the reader locked.\n    reader.releaseLock()\n  }\n}\n"],"names":[],"mappings":"AAgBA,eAAsB,cAAc,QAAyD;AAC3F,QAAM,SAAS,OAAO,UAAA;AACtB,MAAI;AACF,UAAM,SAAuB,CAAA;AAC7B,QAAI,QAAQ;AACZ,WAAO,MAAM;AACX,YAAM,EAAE,MAAM,MAAA,IAAU,MAAM,OAAO,KAAA;AACrC,UAAI,KAAM;AACV,aAAO,KAAK,KAAK;AACjB,eAAS,MAAM;AAAA,IACjB;AACA,UAAM,SAAS,IAAI,WAAW,KAAK;AACnC,QAAI,SAAS;AACb,eAAW,SAAS,QAAQ;AAC1B,aAAO,IAAI,OAAO,MAAM;AACxB,gBAAU,MAAM;AAAA,IAClB;AACA,WAAO;AAAA,EACT,UAAA;AAIE,WAAO,YAAA;AAAA,EACT;AACF;"}
+{"version":3,"file":"collect.js","names":[],"sources":["../../src/streams/collect.ts"],"sourcesContent":["/**\n * Drain a `ReadableStream<Uint8Array>` into a single contiguous\n * `Uint8Array`. Releases the reader lock on both the happy and error\n * paths so the underlying stream can propagate close / error events to\n * the upstream producer.\n *\n * Used by both `createParallelDownloadStream` (per-range fetch) and\n * `StreamSource.toArrayBuffer` (whole-source materialisation). The two\n * code paths previously hand-rolled the same accumulate-then-concat\n * loop; consolidating here removes ~25 duplicated lines and a class of\n * lock-leak bugs.\n *\n * @param stream - Readable stream to consume. Will be fully drained.\n * @param options - Optional abort signal used to stop a pending read.\n *\n * @returns A new `Uint8Array` containing every byte the stream produced.\n */\nexport async function collectStream(\n  stream: ReadableStream<Uint8Array>,\n  options: { readonly signal?: AbortSignal } = {},\n): Promise<Uint8Array> {\n  const reader = stream.getReader()\n  try {\n    const chunks: Uint8Array[] = []\n    let total = 0\n    while (true) {\n      const { done, value } = await readStreamChunkWithSignal(reader, options.signal)\n      if (done) break\n      chunks.push(value)\n      total += value.byteLength\n    }\n    const result = new Uint8Array(total)\n    let offset = 0\n    for (const chunk of chunks) {\n      result.set(chunk, offset)\n      offset += chunk.byteLength\n    }\n    return result\n  } finally {\n    // Releasing here lets the underlying stream propagate close / error\n    // events to any upstream producer (e.g. a Node `Readable`) even on\n    // the error path where a mid-read throw left the reader locked.\n    reader.releaseLock()\n  }\n}\n\n/**\n * Reads one chunk and rejects when the supplied signal aborts.\n * @param reader - Stream reader to read from.\n * @param signal - Optional abort signal that cancels the read.\n *\n * @returns The next stream read result.\n *\n * @internal\n */\nexport async function readStreamChunkWithSignal<T>(\n  reader: ReadableStreamDefaultReader<T>,\n  signal: AbortSignal | undefined,\n): Promise<ReadableStreamReadResult<T>> {\n  if (signal === undefined) return reader.read()\n  signal.throwIfAborted()\n\n  let removeAbortListener: (() => void) | undefined\n  const abortPromise = new Promise<never>((_, reject) => {\n    const onAbort = (): void => {\n      const reason = abortReason(signal)\n      reject(reason)\n      void reader.cancel(reason).catch(() => {})\n    }\n    signal.addEventListener('abort', onAbort, { once: true })\n    removeAbortListener = () => signal.removeEventListener('abort', onAbort)\n  })\n\n  try {\n    return await Promise.race([reader.read(), abortPromise])\n  } finally {\n    removeAbortListener?.()\n  }\n}\n\nfunction abortReason(signal: AbortSignal): unknown {\n  return signal.reason ?? new DOMException('The operation was aborted.', 'AbortError')\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,eAAsB,cACpB,QACA,UAA6C,CAAC,GACzB;CACrB,MAAM,SAAS,OAAO,UAAU;CAChC,IAAI;EACF,MAAM,SAAuB,CAAC;EAC9B,IAAI,QAAQ;EACZ,OAAO,MAAM;GACX,MAAM,EAAE,MAAM,UAAU,MAAM,0BAA0B,QAAQ,QAAQ,MAAM;GAC9E,IAAI,MAAM;GACV,OAAO,KAAK,KAAK;GACjB,SAAS,MAAM;EACjB;EACA,MAAM,SAAS,IAAI,WAAW,KAAK;EACnC,IAAI,SAAS;EACb,KAAK,MAAM,SAAS,QAAQ;GAC1B,OAAO,IAAI,OAAO,MAAM;GACxB,UAAU,MAAM;EAClB;EACA,OAAO;CACT,UAAU;EAIR,OAAO,YAAY;CACrB;AACF;;;;;;;;;;AAWA,eAAsB,0BACpB,QACA,QACsC;CACtC,IAAI,WAAW,KAAA,GAAW,OAAO,OAAO,KAAK;CAC7C,OAAO,eAAe;CAEtB,IAAI;CACJ,MAAM,eAAe,IAAI,SAAgB,GAAG,WAAW;EACrD,MAAM,gBAAsB;GAC1B,MAAM,SAAS,YAAY,MAAM;GACjC,OAAO,MAAM;GACb,OAAY,OAAO,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;EAC3C;EACA,OAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;EACxD,4BAA4B,OAAO,oBAAoB,SAAS,OAAO;CACzE,CAAC;CAED,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,OAAO,KAAK,GAAG,YAAY,CAAC;CACzD,UAAU;EACR,sBAAsB;CACxB;AACF;AAEA,SAAS,YAAY,QAA8B;CACjD,OAAO,OAAO,UAAU,IAAI,aAAa,8BAA8B,YAAY;AACrF"}

package/dist/streams/file-source.cjs

@@ -0,0 +1,287 @@
+//#region src/streams/file-source.ts
+var FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024;
+var FILE_SOURCE_INTERNAL = Symbol("FileSource.internal");
+/** @internal */
+var fileSourceTestHooks = {};
+function getNodeFsSync() {
+	const fs = globalThis.process?.getBuiltinModule?.("node:fs");
+	if (!isNodeFsSync(fs)) throw new Error("FileSource constructor requires Node.js 22.3+ synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.");
+	return fs;
+}
+function isNodeFsSync(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return typeof value["lstatSync"] === "function";
+}
+async function fileOpenFlags() {
+	const { constants } = await import("node:fs");
+	return constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+}
+function normalizeSliceOffset(value, size) {
+	if (!Number.isFinite(value)) throw new RangeError("FileSource slice offsets must be finite.");
+	const integer = Math.trunc(value);
+	const offset = integer < 0 ? size + integer : integer;
+	return Math.min(Math.max(offset, 0), size);
+}
+function formatFilePath(path) {
+	return path instanceof URL ? path.href : path;
+}
+function identityFromStats(stats) {
+	return {
+		dev: stats.dev,
+		ino: stats.ino,
+		size: stats.size,
+		mtimeMs: stats.mtimeMs,
+		ctimeMs: stats.ctimeMs
+	};
+}
+function assertStableIdentity(path, stats) {
+	if (stats.dev === 0 && stats.ino === 0) throw new Error(`FileSource: ${formatFilePath(path)} is on a filesystem that does not expose stable file identity.`);
+}
+function assertRegularFile(path, stats) {
+	if (!stats.isFile()) throw new Error(`FileSource: ${formatFilePath(path)} is not a regular file.`);
+}
+function validatedIdentityFromStats(path, stats) {
+	assertRegularFile(path, stats);
+	if (shouldComparePosixFileIdentity()) assertStableIdentity(path, stats);
+	return identityFromStats(stats);
+}
+function assertSameIdentity(path, expected, actual, when) {
+	if (shouldComparePosixFileIdentity()) assertStableIdentity(path, actual);
+	if (shouldComparePosixFileIdentity() && (actual.dev !== expected.dev || actual.ino !== expected.ino)) throw new Error(`FileSource: ${formatFilePath(path)} changed ${when}.`);
+	if (actual.size !== expected.size || actual.mtimeMs !== expected.mtimeMs) throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`);
+	if (shouldComparePosixChangeTime() && actual.ctimeMs !== expected.ctimeMs) throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`);
+}
+function isWindows() {
+	if (fileSourceTestHooks.platform !== void 0) return fileSourceTestHooks.platform === "win32";
+	return globalThis.process?.platform === "win32";
+}
+function shouldComparePosixFileIdentity() {
+	return !isWindows();
+}
+function shouldComparePosixChangeTime() {
+	return !isWindows();
+}
+function throwIfAborted(signal) {
+	if (signal === void 0 || !signal.aborted) return;
+	throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+function maxReadSize() {
+	return fileSourceTestHooks.maxReadSize ?? FILE_STREAM_CHUNK_SIZE;
+}
+/* v8 ignore start -- Requires a file to pass identity checks and still EOF mid-range. */
+function rangeEndedEarlyError(path, offset, size) {
+	const end = offset + size;
+	return /* @__PURE__ */ new Error(`FileSource: ${formatFilePath(path)} ended before byte range [${offset}, ${end}) was fully read.`);
+}
+/* v8 ignore stop */
+async function openValidatedFile(path, identity) {
+	const open = fileSourceTestHooks.openFile ?? (await import("node:fs/promises")).open;
+	let file;
+	try {
+		file = await open(path, await fileOpenFlags());
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`FileSource: ${formatFilePath(path)} could not be opened: ${message}`);
+	}
+	try {
+		const stats = await file.stat();
+		assertRegularFile(path, stats);
+		assertSameIdentity(path, identity, stats, "before read");
+		return file;
+	} catch (err) {
+		/* v8 ignore next -- Cleanup failure is deliberately best-effort. */
+		await file.close().catch(() => {});
+		throw err;
+	}
+}
+async function lstatNodeFile(path) {
+	const { lstat } = await import("node:fs/promises");
+	return lstat(path);
+}
+async function readFileRange(path, identity, offset, size, signal) {
+	throwIfAborted(signal);
+	if (size === 0) {
+		await verifyFileIdentityForEmptyRead(path, identity, signal);
+		return /* @__PURE__ */ new Uint8Array(0);
+	}
+	throwIfAborted(signal);
+	const file = await openValidatedFile(path, identity);
+	const data = new Uint8Array(size);
+	let filled = 0;
+	try {
+		while (filled < data.byteLength) {
+			throwIfAborted(signal);
+			const length = Math.min(maxReadSize(), data.byteLength - filled);
+			const { bytesRead } = await file.read(data, filled, length, offset + filled);
+			if (bytesRead === 0) throw rangeEndedEarlyError(path, offset, size);
+			filled += bytesRead;
+			await fileSourceTestHooks.afterReadIteration?.(filled);
+		}
+		throwIfAborted(signal);
+		assertSameIdentity(path, identity, await file.stat(), "while being read");
+		return data;
+	} finally {
+		/* v8 ignore next -- Cleanup failure is deliberately best-effort. */
+		await file.close().catch(() => {});
+	}
+}
+async function verifyFileIdentityForEmptyRead(path, identity, signal) {
+	throwIfAborted(signal);
+	const file = await openValidatedFile(path, identity);
+	try {
+		throwIfAborted(signal);
+		return;
+	} finally {
+		/* v8 ignore next -- Cleanup failure is deliberately best-effort. */
+		await file.close().catch(() => {});
+	}
+}
+function sliceFileRange(path, identity, offset, size, start, end) {
+	const normalizedStart = normalizeSliceOffset(start, size);
+	const normalizedEnd = normalizeSliceOffset(end, size);
+	return new FileSliceSource(path, identity, offset + normalizedStart, Math.max(normalizedEnd - normalizedStart, 0));
+}
+function streamFileRange(path, identity, offset, size) {
+	let position = offset;
+	let remaining = size;
+	let verifiedEmpty = false;
+	const abortController = new AbortController();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				if (remaining === 0) {
+					if (!verifiedEmpty) {
+						verifiedEmpty = true;
+						await verifyFileIdentityForEmptyRead(path, identity);
+					}
+					controller.close();
+					return;
+				}
+				const data = await readFileRange(path, identity, position, Math.min(FILE_STREAM_CHUNK_SIZE, remaining), abortController.signal);
+				position += data.byteLength;
+				remaining -= data.byteLength;
+				controller.enqueue(data);
+				if (remaining === 0) controller.close();
+			} catch (err) {
+				controller.error(err);
+			}
+		},
+		cancel(reason) {
+			abortController.abort(reason);
+		}
+	});
+}
+async function fileRangeToArrayBuffer(path, identity, offset, size, options = {}) {
+	return (await readFileRange(path, identity, offset, size, options.signal)).buffer;
+}
+var FileSliceSource = class {
+	path;
+	identity;
+	offset;
+	size;
+	canSlice = true;
+	constructor(path, identity, offset, size) {
+		this.path = path;
+		this.identity = identity;
+		this.offset = offset;
+		this.size = size;
+	}
+	slice(start, end) {
+		return sliceFileRange(this.path, this.identity, this.offset, this.size, start, end);
+	}
+	stream() {
+		return streamFileRange(this.path, this.identity, this.offset, this.size);
+	}
+	toArrayBuffer(options = {}) {
+		return fileRangeToArrayBuffer(this.path, this.identity, this.offset, this.size, options);
+	}
+};
+/**
+* ContentSource backed by a local filesystem path.
+*
+* `FileSource` is Node-only but safe to import in browser builds: it touches
+* Node filesystem APIs only when constructed or read. The constructor performs
+* synchronous filesystem validation so `size` is immediately available; request
+* handlers, sync loops, and other latency-sensitive code should use
+* {@link FileSource.fromPath}. Both paths capture a best-effort regular file
+* identity and reject a symlink as the final path component; parent directory
+* symlinks are followed by the operating system, so callers that constrain
+* paths under a trusted root should validate those parents separately. Reads
+* reject if the path is replaced, if the filesystem cannot report stable
+* identity on POSIX platforms, or if size/mtime/ctime changes before the
+* configured byte range is read. On Windows, reads avoid unreliable dev/inode
+* identity comparisons and validate size/mtime instead.
+* Slices preserve the captured identity, so multipart uploads can read
+* disjoint ranges without materialising the whole file in memory or following
+* later leaf path swaps.
+*/
+var FileSource = class {
+	/** Random-access: file ranges are read by absolute byte offset. */
+	canSlice = true;
+	/** File size captured at construction time. */
+	size;
+	path;
+	identity;
+	/**
+	* Internal constructor path for async validation.
+	* @param path - Local filesystem path or file URL.
+	* @param internal - Module-private validated identity payload.
+	*
+	* @internal
+	*/
+	constructor(path, internal) {
+		const resolvedIdentity = internal?.key === FILE_SOURCE_INTERNAL ? internal.identity : validatedIdentityFromStats(path, getNodeFsSync().lstatSync(path));
+		this.path = path;
+		this.identity = resolvedIdentity;
+		this.size = resolvedIdentity.size;
+	}
+	/**
+	* Return a new file-backed source covering the specified byte range.
+	* @param start - The zero-based byte offset to begin the slice.
+	* @param end - The exclusive byte offset where the slice ends.
+	*
+	* @returns A new ContentSource representing the requested sub-range.
+	*/
+	slice(start, end) {
+		return sliceFileRange(this.path, this.identity, 0, this.size, start, end);
+	}
+	/**
+	* Open this file as a Web ReadableStream.
+	* @returns A ReadableStream that reads the file lazily.
+	*/
+	stream() {
+		return streamFileRange(this.path, this.identity, 0, this.size);
+	}
+	/**
+	* Read this file into an ArrayBuffer.
+	* @param options - Optional abort signal used while reading.
+	*
+	* @returns A promise resolving with the file bytes.
+	*/
+	toArrayBuffer(options = {}) {
+		return fileRangeToArrayBuffer(this.path, this.identity, 0, this.size, options);
+	}
+	/**
+	* Create a FileSource using asynchronous filesystem validation.
+	* @param path - Local filesystem path or file URL.
+	*
+	* @returns A FileSource bound to the validated file identity.
+	*
+	* @throws If the path does not reference a regular non-symlink file.
+	* @throws If a POSIX filesystem cannot report stable file identity.
+	*/
+	static async fromPath(path) {
+		return constructFileSourceFromIdentity(path, validatedIdentityFromStats(path, await lstatNodeFile(path)));
+	}
+};
+function constructFileSourceFromIdentity(path, identity) {
+	return Reflect.construct(FileSource, [path, {
+		key: FILE_SOURCE_INTERNAL,
+		identity
+	}]);
+}
+//#endregion
+exports.FileSource = FileSource;
+exports.fileSourceTestHooks = fileSourceTestHooks;
+
+//# sourceMappingURL=file-source.cjs.map

package/dist/streams/file-source.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.cjs","names":[],"sources":["../../src/streams/file-source.ts"],"sourcesContent":["import type { ContentSource } from './source.ts'\n\nconst FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024\n\n/** Filesystem path accepted by {@link FileSource}. */\nexport type FileSourcePath = string | URL\n\ninterface FileStatsLike {\n  readonly dev: number\n  readonly ino: number\n  readonly mode: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  isFile(): boolean\n}\n\ninterface FileHandleLike {\n  read(\n    buffer: Uint8Array,\n    offset: number,\n    length: number,\n    position: number,\n  ): Promise<{ bytesRead: number }>\n  stat(): Promise<FileStatsLike>\n  close(): Promise<void>\n}\n\ninterface NodeFsSync {\n  lstatSync(path: FileSourcePath): FileStatsLike\n}\n\ninterface FileIdentity {\n  readonly dev: number\n  readonly ino: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n}\n\ninterface ToArrayBufferOptions {\n  readonly signal?: AbortSignal\n}\n\nconst FILE_SOURCE_INTERNAL = Symbol('FileSource.internal')\n\ninterface FileSourceInternalOptions {\n  readonly key: typeof FILE_SOURCE_INTERNAL\n  readonly identity: FileIdentity\n}\n\n/** @internal */\nexport const fileSourceTestHooks: {\n  afterReadIteration?: (filled: number) => Promise<void> | void\n  maxReadSize?: number\n  openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>\n  platform?: string\n} = {}\n\nfunction getNodeFsSync(): NodeFsSync {\n  // FileSource exposes `size` synchronously, so the constructor cannot use the\n  // repo's usual `await import('node:...')` pattern for Node-only APIs. Keep the\n  // synchronous lookup here; async callers should prefer `FileSource.fromPath()`.\n  const processLike = (\n    globalThis as {\n      process?: { getBuiltinModule?: (id: string) => unknown }\n    }\n  ).process\n  const fs = processLike?.getBuiltinModule?.('node:fs')\n  if (!isNodeFsSync(fs)) {\n    throw new Error(\n      'FileSource constructor requires Node.js 22.3+ synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.',\n    )\n  }\n  return fs\n}\n\nfunction isNodeFsSync(value: unknown): value is NodeFsSync {\n  if (typeof value !== 'object' || value === null) return false\n  const candidate = value as Record<string, unknown>\n  return typeof candidate['lstatSync'] === 'function'\n}\n\nasync function fileOpenFlags(): Promise<number> {\n  const { constants } = await import('node:fs')\n  // O_NOFOLLOW and O_NONBLOCK are unavailable on some platforms. When\n  // O_NOFOLLOW is absent, the post-open fstat identity check below is the\n  // symlink-swap defense. O_NONBLOCK avoids blocking indefinitely if a path is\n  // swapped to a FIFO or another blocking special file before fstat rejects it.\n  return (\n    constants.O_RDONLY |\n    (constants.O_NOFOLLOW ?? 0) |\n    ((constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0)\n  )\n}\n\nfunction normalizeSliceOffset(value: number, size: number): number {\n  if (!Number.isFinite(value)) throw new RangeError('FileSource slice offsets must be finite.')\n  const integer = Math.trunc(value)\n  const offset = integer < 0 ? size + integer : integer\n  return Math.min(Math.max(offset, 0), size)\n}\n\nfunction formatFilePath(path: FileSourcePath): string {\n  return path instanceof URL ? path.href : path\n}\n\nfunction identityFromStats(stats: FileStatsLike): FileIdentity {\n  return {\n    dev: stats.dev,\n    ino: stats.ino,\n    size: stats.size,\n    mtimeMs: stats.mtimeMs,\n    ctimeMs: stats.ctimeMs,\n  }\n}\n\nfunction assertStableIdentity(path: FileSourcePath, stats: FileStatsLike): void {\n  if (stats.dev === 0 && stats.ino === 0) {\n    throw new Error(\n      `FileSource: ${formatFilePath(path)} is on a filesystem that does not expose stable file identity.`,\n    )\n  }\n}\n\nfunction assertRegularFile(path: FileSourcePath, stats: FileStatsLike): void {\n  if (!stats.isFile()) {\n    throw new Error(`FileSource: ${formatFilePath(path)} is not a regular file.`)\n  }\n}\n\nfunction validatedIdentityFromStats(path: FileSourcePath, stats: FileStatsLike): FileIdentity {\n  assertRegularFile(path, stats)\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, stats)\n  return identityFromStats(stats)\n}\n\nfunction assertSameIdentity(\n  path: FileSourcePath,\n  expected: FileIdentity,\n  actual: FileStatsLike,\n  when: string,\n): void {\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, actual)\n  if (\n    shouldComparePosixFileIdentity() &&\n    (actual.dev !== expected.dev || actual.ino !== expected.ino)\n  ) {\n    throw new Error(`FileSource: ${formatFilePath(path)} changed ${when}.`)\n  }\n  if (actual.size !== expected.size || actual.mtimeMs !== expected.mtimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n  if (shouldComparePosixChangeTime() && actual.ctimeMs !== expected.ctimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n}\n\nfunction isWindows(): boolean {\n  if (fileSourceTestHooks.platform !== undefined) return fileSourceTestHooks.platform === 'win32'\n  const processLike = (globalThis as { process?: { platform?: string } }).process\n  return processLike?.platform === 'win32'\n}\n\nfunction shouldComparePosixFileIdentity(): boolean {\n  return !isWindows()\n}\n\nfunction shouldComparePosixChangeTime(): boolean {\n  return !isWindows()\n}\n\nfunction throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal === undefined || !signal.aborted) return\n  throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\nfunction maxReadSize(): number {\n  return fileSourceTestHooks.maxReadSize ?? FILE_STREAM_CHUNK_SIZE\n}\n\n/* v8 ignore start -- Requires a file to pass identity checks and still EOF mid-range. */\nfunction rangeEndedEarlyError(path: FileSourcePath, offset: number, size: number): Error {\n  const end = offset + size\n  return new Error(\n    `FileSource: ${formatFilePath(path)} ended before byte range [${offset}, ${end}) was fully read.`,\n  )\n}\n/* v8 ignore stop */\n\nasync function openValidatedFile(\n  path: FileSourcePath,\n  identity: FileIdentity,\n): Promise<FileHandleLike> {\n  const open =\n    fileSourceTestHooks.openFile ??\n    (\n      (await import('node:fs/promises')) as {\n        open(path: FileSourcePath, flags: number): Promise<FileHandleLike>\n      }\n    ).open\n  let file: FileHandleLike\n  try {\n    file = await open(path, await fileOpenFlags())\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    throw new Error(`FileSource: ${formatFilePath(path)} could not be opened: ${message}`)\n  }\n\n  try {\n    const stats = await file.stat()\n    assertRegularFile(path, stats)\n    assertSameIdentity(path, identity, stats, 'before read')\n    return file\n  } catch (err) {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n    throw err\n  }\n}\n\nasync function lstatNodeFile(path: FileSourcePath): Promise<FileStatsLike> {\n  const { lstat } = (await import('node:fs/promises')) as {\n    lstat(path: FileSourcePath): Promise<FileStatsLike>\n  }\n  return lstat(path)\n}\n\nasync function readFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  signal?: AbortSignal,\n): Promise<Uint8Array> {\n  throwIfAborted(signal)\n  if (size === 0) {\n    await verifyFileIdentityForEmptyRead(path, identity, signal)\n    return new Uint8Array(0)\n  }\n\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  const data = new Uint8Array(size)\n  let filled = 0\n  try {\n    while (filled < data.byteLength) {\n      throwIfAborted(signal)\n      const length = Math.min(maxReadSize(), data.byteLength - filled)\n      const { bytesRead } = await file.read(data, filled, length, offset + filled)\n      if (bytesRead === 0) throw rangeEndedEarlyError(path, offset, size)\n      filled += bytesRead\n      await fileSourceTestHooks.afterReadIteration?.(filled)\n    }\n    throwIfAborted(signal)\n    const stats = await file.stat()\n    assertSameIdentity(path, identity, stats, 'while being read')\n    return data\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nasync function verifyFileIdentityForEmptyRead(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  signal?: AbortSignal,\n): Promise<void> {\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  try {\n    throwIfAborted(signal)\n    return\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nfunction sliceFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  start: number,\n  end: number,\n): ContentSource {\n  const normalizedStart = normalizeSliceOffset(start, size)\n  const normalizedEnd = normalizeSliceOffset(end, size)\n  return new FileSliceSource(\n    path,\n    identity,\n    offset + normalizedStart,\n    Math.max(normalizedEnd - normalizedStart, 0),\n  )\n}\n\nfunction streamFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n): ReadableStream<Uint8Array> {\n  let position = offset\n  let remaining = size\n  let verifiedEmpty = false\n  const abortController = new AbortController()\n\n  // Open per pull so abandoned public streams do not strand file handles or\n  // retain Windows locks. Each chunk still verifies identity around its read.\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        if (remaining === 0) {\n          if (!verifiedEmpty) {\n            verifiedEmpty = true\n            await verifyFileIdentityForEmptyRead(path, identity)\n          }\n          controller.close()\n          return\n        }\n\n        const length = Math.min(FILE_STREAM_CHUNK_SIZE, remaining)\n        const data = await readFileRange(path, identity, position, length, abortController.signal)\n        position += data.byteLength\n        remaining -= data.byteLength\n        controller.enqueue(data)\n        if (remaining === 0) controller.close()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortController.abort(reason)\n    },\n  })\n}\n\nasync function fileRangeToArrayBuffer(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  options: ToArrayBufferOptions = {},\n): Promise<ArrayBuffer> {\n  const data = await readFileRange(path, identity, offset, size, options.signal)\n  return data.buffer as ArrayBuffer\n}\n\nclass FileSliceSource implements ContentSource {\n  readonly canSlice = true\n\n  constructor(\n    private readonly path: FileSourcePath,\n    private readonly identity: FileIdentity,\n    private readonly offset: number,\n    readonly size: number,\n  ) {}\n\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, this.offset, this.size, start, end)\n  }\n\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, this.offset, this.size)\n  }\n\n  toArrayBuffer(options: ToArrayBufferOptions = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, this.offset, this.size, options)\n  }\n}\n\n/**\n * ContentSource backed by a local filesystem path.\n *\n * `FileSource` is Node-only but safe to import in browser builds: it touches\n * Node filesystem APIs only when constructed or read. The constructor performs\n * synchronous filesystem validation so `size` is immediately available; request\n * handlers, sync loops, and other latency-sensitive code should use\n * {@link FileSource.fromPath}. Both paths capture a best-effort regular file\n * identity and reject a symlink as the final path component; parent directory\n * symlinks are followed by the operating system, so callers that constrain\n * paths under a trusted root should validate those parents separately. Reads\n * reject if the path is replaced, if the filesystem cannot report stable\n * identity on POSIX platforms, or if size/mtime/ctime changes before the\n * configured byte range is read. On Windows, reads avoid unreliable dev/inode\n * identity comparisons and validate size/mtime instead.\n * Slices preserve the captured identity, so multipart uploads can read\n * disjoint ranges without materialising the whole file in memory or following\n * later leaf path swaps.\n */\nexport class FileSource implements ContentSource {\n  /** Random-access: file ranges are read by absolute byte offset. */\n  readonly canSlice = true\n  /** File size captured at construction time. */\n  readonly size: number\n  private readonly path: FileSourcePath\n  private readonly identity: FileIdentity\n\n  /**\n   * Create a FileSource for a local file path.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @throws If the runtime has no Node-compatible filesystem API.\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  constructor(path: FileSourcePath)\n  /**\n   * Internal constructor path for async validation.\n   * @param path - Local filesystem path or file URL.\n   * @param internal - Module-private validated identity payload.\n   *\n   * @internal\n   */\n  constructor(path: FileSourcePath, internal?: FileSourceInternalOptions) {\n    const resolvedIdentity =\n      internal?.key === FILE_SOURCE_INTERNAL\n        ? internal.identity\n        : validatedIdentityFromStats(path, getNodeFsSync().lstatSync(path))\n    this.path = path\n    this.identity = resolvedIdentity\n    this.size = resolvedIdentity.size\n  }\n\n  /**\n   * Return a new file-backed source covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, 0, this.size, start, end)\n  }\n\n  /**\n   * Open this file as a Web ReadableStream.\n   * @returns A ReadableStream that reads the file lazily.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, 0, this.size)\n  }\n\n  /**\n   * Read this file into an ArrayBuffer.\n   * @param options - Optional abort signal used while reading.\n   *\n   * @returns A promise resolving with the file bytes.\n   */\n  toArrayBuffer(options: { readonly signal?: AbortSignal } = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, 0, this.size, options)\n  }\n\n  /**\n   * Create a FileSource using asynchronous filesystem validation.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @returns A FileSource bound to the validated file identity.\n   *\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  static async fromPath(path: FileSourcePath): Promise<FileSource> {\n    const identity = validatedIdentityFromStats(path, await lstatNodeFile(path))\n    return constructFileSourceFromIdentity(path, identity)\n  }\n}\n\nfunction constructFileSourceFromIdentity(path: FileSourcePath, identity: FileIdentity): FileSource {\n  // The public overload is intentionally single-argument; Reflect.construct\n  // lets fromPath pass the module-private validated identity without exposing\n  // that constructor shape in the public type surface.\n  return Reflect.construct(FileSource, [\n    path,\n    { key: FILE_SOURCE_INTERNAL, identity },\n  ]) as FileSource\n}\n"],"mappings":"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"}

package/dist/streams/file-source.d.cts

@@ -0,0 +1,96 @@
+import { ContentSource } from './source.js';
+/** Filesystem path accepted by {@link FileSource}. */
+export type FileSourcePath = string | URL;
+interface FileStatsLike {
+    readonly dev: number;
+    readonly ino: number;
+    readonly mode: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+    isFile(): boolean;
+}
+interface FileHandleLike {
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    stat(): Promise<FileStatsLike>;
+    close(): Promise<void>;
+}
+/** @internal */
+export declare const fileSourceTestHooks: {
+    afterReadIteration?: (filled: number) => Promise<void> | void;
+    maxReadSize?: number;
+    openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>;
+    platform?: string;
+};
+/**
+ * ContentSource backed by a local filesystem path.
+ *
+ * `FileSource` is Node-only but safe to import in browser builds: it touches
+ * Node filesystem APIs only when constructed or read. The constructor performs
+ * synchronous filesystem validation so `size` is immediately available; request
+ * handlers, sync loops, and other latency-sensitive code should use
+ * {@link FileSource.fromPath}. Both paths capture a best-effort regular file
+ * identity and reject a symlink as the final path component; parent directory
+ * symlinks are followed by the operating system, so callers that constrain
+ * paths under a trusted root should validate those parents separately. Reads
+ * reject if the path is replaced, if the filesystem cannot report stable
+ * identity on POSIX platforms, or if size/mtime/ctime changes before the
+ * configured byte range is read. On Windows, reads avoid unreliable dev/inode
+ * identity comparisons and validate size/mtime instead.
+ * Slices preserve the captured identity, so multipart uploads can read
+ * disjoint ranges without materialising the whole file in memory or following
+ * later leaf path swaps.
+ */
+export declare class FileSource implements ContentSource {
+    /** Random-access: file ranges are read by absolute byte offset. */
+    readonly canSlice = true;
+    /** File size captured at construction time. */
+    readonly size: number;
+    private readonly path;
+    private readonly identity;
+    /**
+     * Create a FileSource for a local file path.
+     * @param path - Local filesystem path or file URL.
+     *
+     * @throws If the runtime has no Node-compatible filesystem API.
+     * @throws If the path does not reference a regular non-symlink file.
+     * @throws If a POSIX filesystem cannot report stable file identity.
+     */
+    constructor(path: FileSourcePath);
+    /**
+     * Return a new file-backed source covering the specified byte range.
+     * @param start - The zero-based byte offset to begin the slice.
+     * @param end - The exclusive byte offset where the slice ends.
+     *
+     * @returns A new ContentSource representing the requested sub-range.
+     */
+    slice(start: number, end: number): ContentSource;
+    /**
+     * Open this file as a Web ReadableStream.
+     * @returns A ReadableStream that reads the file lazily.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read this file into an ArrayBuffer.
+     * @param options - Optional abort signal used while reading.
+     *
+     * @returns A promise resolving with the file bytes.
+     */
+    toArrayBuffer(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ArrayBuffer>;
+    /**
+     * Create a FileSource using asynchronous filesystem validation.
+     * @param path - Local filesystem path or file URL.
+     *
+     * @returns A FileSource bound to the validated file identity.
+     *
+     * @throws If the path does not reference a regular non-symlink file.
+     * @throws If a POSIX filesystem cannot report stable file identity.
+     */
+    static fromPath(path: FileSourcePath): Promise<FileSource>;
+}
+export {};
+//# sourceMappingURL=file-source.d.ts.map

package/dist/streams/file-source.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.d.ts","sourceRoot":"","sources":["../../src/streams/file-source.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAIhD,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,GAAG,CAAA;AAEzC,UAAU,aAAa;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,MAAM,IAAI,OAAO,CAAA;CAClB;AAED,UAAU,cAAc;IACtB,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,CAAA;IACjC,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAyBD,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,EAAE;IAChC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AA4TN;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAW,YAAW,aAAa;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,QAAO;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IAEvC;;;;;;;OAOG;gBACS,IAAI,EAAE,cAAc;IAkBhC;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAIhD;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAIpC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAIpF;;;;;;;;OAQG;WACU,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;CAIjE"}

package/dist/streams/file-source.d.ts

@@ -0,0 +1,96 @@
+import { ContentSource } from './source.js';
+/** Filesystem path accepted by {@link FileSource}. */
+export type FileSourcePath = string | URL;
+interface FileStatsLike {
+    readonly dev: number;
+    readonly ino: number;
+    readonly mode: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+    isFile(): boolean;
+}
+interface FileHandleLike {
+    read(buffer: Uint8Array, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    stat(): Promise<FileStatsLike>;
+    close(): Promise<void>;
+}
+/** @internal */
+export declare const fileSourceTestHooks: {
+    afterReadIteration?: (filled: number) => Promise<void> | void;
+    maxReadSize?: number;
+    openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>;
+    platform?: string;
+};
+/**
+ * ContentSource backed by a local filesystem path.
+ *
+ * `FileSource` is Node-only but safe to import in browser builds: it touches
+ * Node filesystem APIs only when constructed or read. The constructor performs
+ * synchronous filesystem validation so `size` is immediately available; request
+ * handlers, sync loops, and other latency-sensitive code should use
+ * {@link FileSource.fromPath}. Both paths capture a best-effort regular file
+ * identity and reject a symlink as the final path component; parent directory
+ * symlinks are followed by the operating system, so callers that constrain
+ * paths under a trusted root should validate those parents separately. Reads
+ * reject if the path is replaced, if the filesystem cannot report stable
+ * identity on POSIX platforms, or if size/mtime/ctime changes before the
+ * configured byte range is read. On Windows, reads avoid unreliable dev/inode
+ * identity comparisons and validate size/mtime instead.
+ * Slices preserve the captured identity, so multipart uploads can read
+ * disjoint ranges without materialising the whole file in memory or following
+ * later leaf path swaps.
+ */
+export declare class FileSource implements ContentSource {
+    /** Random-access: file ranges are read by absolute byte offset. */
+    readonly canSlice = true;
+    /** File size captured at construction time. */
+    readonly size: number;
+    private readonly path;
+    private readonly identity;
+    /**
+     * Create a FileSource for a local file path.
+     * @param path - Local filesystem path or file URL.
+     *
+     * @throws If the runtime has no Node-compatible filesystem API.
+     * @throws If the path does not reference a regular non-symlink file.
+     * @throws If a POSIX filesystem cannot report stable file identity.
+     */
+    constructor(path: FileSourcePath);
+    /**
+     * Return a new file-backed source covering the specified byte range.
+     * @param start - The zero-based byte offset to begin the slice.
+     * @param end - The exclusive byte offset where the slice ends.
+     *
+     * @returns A new ContentSource representing the requested sub-range.
+     */
+    slice(start: number, end: number): ContentSource;
+    /**
+     * Open this file as a Web ReadableStream.
+     * @returns A ReadableStream that reads the file lazily.
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * Read this file into an ArrayBuffer.
+     * @param options - Optional abort signal used while reading.
+     *
+     * @returns A promise resolving with the file bytes.
+     */
+    toArrayBuffer(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ArrayBuffer>;
+    /**
+     * Create a FileSource using asynchronous filesystem validation.
+     * @param path - Local filesystem path or file URL.
+     *
+     * @returns A FileSource bound to the validated file identity.
+     *
+     * @throws If the path does not reference a regular non-symlink file.
+     * @throws If a POSIX filesystem cannot report stable file identity.
+     */
+    static fromPath(path: FileSourcePath): Promise<FileSource>;
+}
+export {};
+//# sourceMappingURL=file-source.d.ts.map

package/dist/streams/file-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-source.d.ts","sourceRoot":"","sources":["../../src/streams/file-source.js"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAIhD,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,GAAG,CAAA;AAEzC,UAAU,aAAa;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,MAAM,IAAI,OAAO,CAAA;CAClB;AAED,UAAU,cAAc;IACtB,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,CAAA;IACjC,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAyBD,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,EAAE;IAChC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;CACb,CAAA;AA4TN;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAW,YAAW,aAAa;IAC9C,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,QAAO;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IAEvC;;;;;;;OAOG;gBACS,IAAI,EAAE,cAAc;IAkBhC;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAIhD;;;OAGG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IAIpC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAIpF;;;;;;;;OAQG;WACU,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;CAIjE"}