@freqhole/reliquary 0.0.0

package/dist/testing/mock-node.js

@@ -0,0 +1,97 @@
+// pushable test doubles for the automerge/transfer transport surface: a
+// `BiStreamLike` whose reads and writes a test can drive by hand, and a
+// `MiddenStreamNode`-shaped node that opens/accepts those streams.
+//
+// every method is a `vi.fn()` so a consuming test can assert on call
+// counts/arguments or override a single call's behavior (`mockResolvedValueOnce`,
+// `mockRejectedValueOnce`, ...) without replacing the whole double.
+//
+// dialing (`open_bi`) on the mock node always succeeds and hands back a
+// fresh mock stream addressed to whatever peer id was dialed - a test
+// wanting to simulate a dial failure overrides `open_bi` for one call via
+// `mockRejectedValueOnce` instead.
+import { vi } from "vitest";
+/** creates a mock bidirectional stream addressed to `peerId`. reads block
+ *  until a message is pushed via `pushMessage`; writes are recorded in
+ *  `_written` for assertions. */
+export function createMockBiStream(peerId, alpn = "iroh/automerge-repo/1") {
+    const stream = {
+        _messageQueue: [],
+        _written: [],
+        _closed: false,
+        _readResolvers: [],
+        peer_node_id: () => peerId,
+        alpn: () => alpn,
+        write_message: vi.fn(async (data) => {
+            stream._written.push(data);
+        }),
+        read_message: vi.fn(async () => {
+            if (stream._messageQueue.length > 0) {
+                return stream._messageQueue.shift();
+            }
+            return new Promise((resolve) => {
+                stream._readResolvers.push(resolve);
+            });
+        }),
+        read_to_end: vi.fn(async (max_size) => {
+            if (stream._messageQueue.length > 0) {
+                const data = stream._messageQueue.shift();
+                return data ?? new Uint8Array(0);
+            }
+            return new Promise((resolve) => {
+                const originalResolver = (value) => {
+                    resolve(value ?? new Uint8Array(0));
+                };
+                stream._readResolvers.push(originalResolver);
+            });
+        }),
+        write_raw_and_finish: vi.fn(async (data) => {
+            stream._written.push(data);
+            stream._closed = true;
+        }),
+        close: vi.fn(() => {
+            stream._closed = true;
+            for (const resolve of stream._readResolvers) {
+                resolve(null);
+            }
+            stream._readResolvers = [];
+        }),
+        pushMessage(data) {
+            if (stream._readResolvers.length > 0) {
+                stream._readResolvers.shift()(data);
+            }
+            else {
+                stream._messageQueue.push(data);
+            }
+        },
+    };
+    return stream;
+}
+/** creates a mock midden node identified by `nodeId`. */
+export function createMockMidden(nodeId = "a".repeat(64)) {
+    const acceptQueue = [];
+    const acceptResolvers = [];
+    const midden = {
+        node_id: () => nodeId,
+        open_bi: vi.fn(async (addr) => {
+            return createMockBiStream(addr);
+        }),
+        accept: vi.fn(async () => {
+            if (acceptQueue.length > 0) {
+                return acceptQueue.shift();
+            }
+            return new Promise((resolve) => {
+                acceptResolvers.push(resolve);
+            });
+        }),
+        pushIncoming(stream) {
+            if (acceptResolvers.length > 0) {
+                acceptResolvers.shift()(stream);
+            }
+            else {
+                acceptQueue.push(stream);
+            }
+        },
+    };
+    return midden;
+}

package/dist/testing/mock-node.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mock-node.test.d.ts.map

package/dist/testing/mock-node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-node.test.d.ts","sourceRoot":"","sources":["../../src/testing/mock-node.test.ts"],"names":[],"mappings":""}

package/dist/testing/mock-node.test.js

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { createMockBiStream, createMockMidden } from "./mock-node.js";
+describe("createMockBiStream", () => {
+    it("reports the peer id and alpn it was created with", () => {
+        const stream = createMockBiStream("peer-x", "test-alpn/1");
+        expect(stream.peer_node_id()).toBe("peer-x");
+        expect(stream.alpn()).toBe("test-alpn/1");
+    });
+    it("defaults to the automerge sync alpn", () => {
+        const stream = createMockBiStream("peer-x");
+        expect(stream.alpn()).toBe("iroh/automerge-repo/1");
+    });
+    it("records every write in _written", async () => {
+        const stream = createMockBiStream("peer-x");
+        const a = new Uint8Array([1, 2, 3]);
+        const b = new Uint8Array([4, 5]);
+        await stream.write_message(a);
+        await stream.write_message(b);
+        expect(stream._written).toEqual([a, b]);
+    });
+    it("read_message resolves with a message pushed before the read starts", async () => {
+        const stream = createMockBiStream("peer-x");
+        const data = new Uint8Array([9, 9]);
+        stream.pushMessage(data);
+        await expect(stream.read_message()).resolves.toBe(data);
+    });
+    it("read_message resolves once a message is pushed after the read starts", async () => {
+        const stream = createMockBiStream("peer-x");
+        const pending = stream.read_message();
+        const data = new Uint8Array([7]);
+        stream.pushMessage(data);
+        await expect(pending).resolves.toBe(data);
+    });
+    it("close() marks the stream closed and resolves any pending read with null", async () => {
+        const stream = createMockBiStream("peer-x");
+        const pending = stream.read_message();
+        stream.close();
+        expect(stream._closed).toBe(true);
+        await expect(pending).resolves.toBeNull();
+    });
+});
+describe("createMockMidden", () => {
+    it("reports the node id it was created with, defaulting to a 64-char id", () => {
+        const midden = createMockMidden("my-node");
+        expect(midden.node_id()).toBe("my-node");
+        expect(createMockMidden().node_id()).toHaveLength(64);
+    });
+    it("open_bi resolves with a mock stream addressed to the dialed peer", async () => {
+        const midden = createMockMidden();
+        const stream = await midden.open_bi("peer-y", "some-alpn");
+        expect(stream.peer_node_id()).toBe("peer-y");
+    });
+    it("accept resolves with a stream pushed before the accept starts", async () => {
+        const midden = createMockMidden();
+        const incoming = createMockBiStream("peer-z");
+        midden.pushIncoming(incoming);
+        await expect(midden.accept()).resolves.toBe(incoming);
+    });
+    it("accept resolves once a stream is pushed after the accept starts", async () => {
+        const midden = createMockMidden();
+        const pending = midden.accept();
+        const incoming = createMockBiStream("peer-z");
+        midden.pushIncoming(incoming);
+        await expect(pending).resolves.toBe(incoming);
+    });
+});

package/dist/testing/streams.d.ts

@@ -0,0 +1,68 @@
+import type { BiStreamLike } from "../automerge/types.js";
+/** encodes a message as utf-8 json bytes. */
+export declare function encodeJsonMessage(message: unknown): Uint8Array;
+/** decodes utf-8 json bytes back into a message. */
+export declare function decodeJsonMessage<TMessage = unknown>(data: Uint8Array): TMessage;
+export interface CollectingStreamOptions<TMessage> {
+    peerId?: string;
+    alpn?: string;
+    /** decodes a written frame into a message for `sent`. defaults to
+     *  `decodeJsonMessage`. */
+    decode?(data: Uint8Array): TMessage;
+}
+/**
+ * a `BiStreamLike` double that never has anything to read and simply
+ * records every write - for exercising the serving side of a protocol in
+ * isolation (assert on what got sent back, without needing a live peer to
+ * read it).
+ */
+export declare class CollectingStream<TMessage = unknown> implements BiStreamLike {
+    readonly sent: TMessage[];
+    private isClosed;
+    private readonly peerId;
+    private readonly streamAlpn;
+    private readonly decode;
+    constructor(options?: CollectingStreamOptions<TMessage>);
+    write_message(data: Uint8Array): Promise<void>;
+    read_message(): Promise<Uint8Array | null>;
+    close(): void;
+    get closed(): boolean;
+    peer_node_id(): string;
+    alpn(): string;
+}
+/** what a scripted serving stream knows about one blob, keyed by whatever
+ *  id the request message addresses it by. */
+export interface ServingStreamEntry {
+    blake3: string;
+    size: number;
+    mime?: string;
+}
+export interface MakeServingStreamOptions<TMessage> {
+    peerId?: string;
+    alpn?: string;
+    encode?(message: TMessage): Uint8Array;
+    decode?(data: Uint8Array): TMessage;
+    /** pulls the requested blob's id out of a decoded write, or `null` when
+     *  the message isn't a blob request. defaults to reading
+     *  `{ type: "blob_request", id }`. */
+    requestId?(message: TMessage): string | null;
+    /** builds the reply for a request id, given the matching table entry
+     *  (or `undefined` on a miss). defaults to
+     *  `{ type: "blob_ready", id, blake3, size, mime }` on a hit and
+     *  `{ type: "error", code: "blob_not_found", id }` on a miss. */
+    buildReply?(id: string, entry: ServingStreamEntry | undefined): TMessage;
+}
+/**
+ * a `BiStreamLike` double that scripts replies to blob-request-shaped
+ * messages from a blake3-keyed lookup table - the fetching side of a
+ * protocol driven against fixed, known responses instead of a live peer.
+ * every write is checked against `requestId`; a match queues a
+ * `buildReply` result to be read back by the next `read_message()` call.
+ */
+export declare function makeServingStream<TMessage = {
+    type: string;
+    id: string;
+}>(table: Record<string, ServingStreamEntry>, options?: MakeServingStreamOptions<TMessage>): BiStreamLike & {
+    closed: boolean;
+};
+//# sourceMappingURL=streams.d.ts.map

package/dist/testing/streams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../src/testing/streams.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAE9D;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,QAAQ,CAEhF;AAED,MAAM,WAAW,uBAAuB,CAAC,QAAQ;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;+BAC2B;IAC3B,MAAM,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB,CAAC,QAAQ,GAAG,OAAO,CAAE,YAAW,YAAY;IACvE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAE5C,OAAO,GAAE,uBAAuB,CAAC,QAAQ,CAAM;IAMrD,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,YAAY,IAAI,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAIhD,KAAK,IAAI,IAAI;IAIb,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,YAAY,IAAI,MAAM;IAItB,IAAI,IAAI,MAAM;CAGf;AAED;8CAC8C;AAC9C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB,CAAC,QAAQ;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,CAAC,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAC;IACvC,MAAM,CAAC,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IACpC;;0CAEsC;IACtC,SAAS,CAAC,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAC;IAC7C;;;qEAGiE;IACjE,UAAU,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC1E;AAcD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACvE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACzC,OAAO,GAAE,wBAAwB,CAAC,QAAQ,CAAM,GAC/C,YAAY,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CA+BpC"}

package/dist/testing/streams.js

@@ -0,0 +1,99 @@
+// generic `BiStreamLike` doubles for exercising a request/reply protocol
+// built on top of length-delimited messages, without any real peer on the
+// other end: `CollectingStream` records every write for later assertions,
+// and `makeServingStream` scripts replies to blob-request-shaped messages
+// from a blake3-keyed lookup table.
+//
+// both default to a plain json wire format (`encodeJsonMessage`/
+// `decodeJsonMessage`) since this package has no wire protocol of its
+// own to assume - a consumer with its own message codec (cbor, a custom
+// binary framing, ...) supplies its own `encode`/`decode` instead.
+const DEFAULT_ALPN = "reliquary/testing/1";
+const DEFAULT_PEER_ID = "peer-a";
+/** encodes a message as utf-8 json bytes. */
+export function encodeJsonMessage(message) {
+    return new TextEncoder().encode(JSON.stringify(message));
+}
+/** decodes utf-8 json bytes back into a message. */
+export function decodeJsonMessage(data) {
+    return JSON.parse(new TextDecoder().decode(data));
+}
+/**
+ * a `BiStreamLike` double that never has anything to read and simply
+ * records every write - for exercising the serving side of a protocol in
+ * isolation (assert on what got sent back, without needing a live peer to
+ * read it).
+ */
+export class CollectingStream {
+    sent = [];
+    isClosed = false;
+    peerId;
+    streamAlpn;
+    decode;
+    constructor(options = {}) {
+        this.peerId = options.peerId ?? DEFAULT_PEER_ID;
+        this.streamAlpn = options.alpn ?? DEFAULT_ALPN;
+        this.decode = options.decode ?? decodeJsonMessage;
+    }
+    async write_message(data) {
+        this.sent.push(this.decode(data));
+    }
+    async read_message() {
+        return null;
+    }
+    close() {
+        this.isClosed = true;
+    }
+    get closed() {
+        return this.isClosed;
+    }
+    peer_node_id() {
+        return this.peerId;
+    }
+    alpn() {
+        return this.streamAlpn;
+    }
+}
+function defaultRequestId(message) {
+    const m = message;
+    return m.type === "blob_request" && typeof m.id === "string" ? m.id : null;
+}
+function defaultBuildReply(id, entry) {
+    if (!entry) {
+        return { type: "error", code: "blob_not_found", id };
+    }
+    return { type: "blob_ready", id, blake3: entry.blake3, size: entry.size, mime: entry.mime };
+}
+/**
+ * a `BiStreamLike` double that scripts replies to blob-request-shaped
+ * messages from a blake3-keyed lookup table - the fetching side of a
+ * protocol driven against fixed, known responses instead of a live peer.
+ * every write is checked against `requestId`; a match queues a
+ * `buildReply` result to be read back by the next `read_message()` call.
+ */
+export function makeServingStream(table, options = {}) {
+    const encode = options.encode ?? encodeJsonMessage;
+    const decode = options.decode ?? decodeJsonMessage;
+    const requestId = options.requestId ?? defaultRequestId;
+    const buildReply = options.buildReply ?? defaultBuildReply;
+    const replies = [];
+    return {
+        closed: false,
+        async write_message(data) {
+            const message = decode(data);
+            const id = requestId(message);
+            if (id !== null) {
+                replies.push(buildReply(id, table[id]));
+            }
+        },
+        async read_message() {
+            const message = replies.shift();
+            return message === undefined ? null : encode(message);
+        },
+        close() {
+            this.closed = true;
+        },
+        peer_node_id: () => options.peerId ?? DEFAULT_PEER_ID,
+        alpn: () => options.alpn ?? DEFAULT_ALPN,
+    };
+}

package/dist/testing/streams.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=streams.test.d.ts.map

package/dist/testing/streams.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.test.d.ts","sourceRoot":"","sources":["../../src/testing/streams.test.ts"],"names":[],"mappings":""}

package/dist/testing/streams.test.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { CollectingStream, decodeJsonMessage, encodeJsonMessage, makeServingStream } from "./streams.js";
+describe("encodeJsonMessage / decodeJsonMessage", () => {
+    it("round-trips a message", () => {
+        const message = { type: "ping", n: 3 };
+        expect(decodeJsonMessage(encodeJsonMessage(message))).toEqual(message);
+    });
+});
+describe("CollectingStream", () => {
+    it("decodes and records every write", async () => {
+        const stream = new CollectingStream();
+        await stream.write_message(encodeJsonMessage({ type: "hello" }));
+        await stream.write_message(encodeJsonMessage({ type: "world" }));
+        expect(stream.sent).toEqual([{ type: "hello" }, { type: "world" }]);
+    });
+    it("read_message always resolves null", async () => {
+        const stream = new CollectingStream();
+        await expect(stream.read_message()).resolves.toBeNull();
+    });
+    it("tracks closed state", () => {
+        const stream = new CollectingStream();
+        expect(stream.closed).toBe(false);
+        stream.close();
+        expect(stream.closed).toBe(true);
+    });
+    it("uses the given peer id/alpn, defaulting when omitted", () => {
+        const withDefaults = new CollectingStream();
+        expect(withDefaults.peer_node_id()).toBe("peer-a");
+        expect(withDefaults.alpn()).toBe("reliquary/testing/1");
+        const withOverrides = new CollectingStream({ peerId: "peer-q", alpn: "custom/1" });
+        expect(withOverrides.peer_node_id()).toBe("peer-q");
+        expect(withOverrides.alpn()).toBe("custom/1");
+    });
+    it("decodes writes with a caller-supplied codec", async () => {
+        const stream = new CollectingStream({ decode: (data) => new TextDecoder().decode(data) });
+        await stream.write_message(new TextEncoder().encode("raw text"));
+        expect(stream.sent).toEqual(["raw text"]);
+    });
+});
+describe("makeServingStream", () => {
+    const table = {
+        "blob-1": { blake3: "blake3-1", size: 10, mime: "audio/wav" },
+    };
+    it("replies blob_ready for a known id", async () => {
+        const stream = makeServingStream(table);
+        await stream.write_message(encodeJsonMessage({ type: "blob_request", id: "blob-1" }));
+        const reply = decodeJsonMessage(await stream.read_message());
+        expect(reply).toEqual({ type: "blob_ready", id: "blob-1", blake3: "blake3-1", size: 10, mime: "audio/wav" });
+    });
+    it("replies blob_not_found for an unknown id", async () => {
+        const stream = makeServingStream(table);
+        await stream.write_message(encodeJsonMessage({ type: "blob_request", id: "missing" }));
+        const reply = decodeJsonMessage(await stream.read_message());
+        expect(reply).toEqual({ type: "error", code: "blob_not_found", id: "missing" });
+    });
+    it("read_message resolves null once every scripted reply has been read", async () => {
+        const stream = makeServingStream(table);
+        await stream.write_message(encodeJsonMessage({ type: "blob_request", id: "blob-1" }));
+        await stream.read_message();
+        await expect(stream.read_message()).resolves.toBeNull();
+    });
+    it("ignores writes that aren't blob requests", async () => {
+        const stream = makeServingStream(table);
+        await stream.write_message(encodeJsonMessage({ type: "something_else" }));
+        await expect(stream.read_message()).resolves.toBeNull();
+    });
+    it("tracks closed state", () => {
+        const stream = makeServingStream(table);
+        expect(stream.closed).toBe(false);
+        stream.close();
+        expect(stream.closed).toBe(true);
+    });
+    it("supports a caller-supplied requestId/buildReply pair for a custom protocol", async () => {
+        const stream = makeServingStream(table, {
+            requestId: (m) => (m.kind === "get" ? (m.hash ?? null) : null),
+            buildReply: (id, entry) => entry ? { kind: "got", hash: id, blake3: entry.blake3, size: entry.size } : { kind: "miss", hash: id },
+        });
+        await stream.write_message(encodeJsonMessage({ kind: "get", hash: "blob-1" }));
+        const reply = decodeJsonMessage((await stream.read_message()));
+        expect(reply).toEqual({ kind: "got", hash: "blob-1", blake3: "blake3-1", size: 10 });
+    });
+});

package/dist/transfer/cancellation.d.ts

@@ -0,0 +1,8 @@
+/** exact error message a transport uses for a deliberately cancelled or
+ *  paused download (as opposed to a transport failure). */
+export declare const DOWNLOAD_CANCELLED_MESSAGE = "download cancelled";
+/** true when `err` represents a deliberate pause/cancel (an AbortError, or
+ *  the exact cancelled-download message above), as opposed to a genuine
+ *  transfer failure. */
+export declare function isCancelledError(err: unknown): boolean;
+//# sourceMappingURL=cancellation.d.ts.map

package/dist/transfer/cancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../../src/transfer/cancellation.ts"],"names":[],"mappings":"AAQA;2DAC2D;AAC3D,eAAO,MAAM,0BAA0B,uBAAuB,CAAC;AAE/D;;wBAEwB;AACxB,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAItD"}

package/dist/transfer/cancellation.js

@@ -0,0 +1,19 @@
+// cancellation detection shared by every ./transfer flow.
+//
+// a deliberate pause/cancel of an in-flight download must never be
+// mistaken for a genuine failure: the per-peer retry loop in `snatch.ts`
+// rethrows a cancelled error immediately instead of trying the next peer,
+// and the disk-streaming path leaves the writable exactly as it is
+// (no truncate) since a resumed download rewrites the same byte offsets.
+/** exact error message a transport uses for a deliberately cancelled or
+ *  paused download (as opposed to a transport failure). */
+export const DOWNLOAD_CANCELLED_MESSAGE = "download cancelled";
+/** true when `err` represents a deliberate pause/cancel (an AbortError, or
+ *  the exact cancelled-download message above), as opposed to a genuine
+ *  transfer failure. */
+export function isCancelledError(err) {
+    if (err instanceof DOMException && err.name === "AbortError")
+        return true;
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes(DOWNLOAD_CANCELLED_MESSAGE);
+}

package/dist/transfer/index.d.ts

@@ -0,0 +1,8 @@
+export type { BlobCapableNode, DiskSnatchResult, SnatchInfo, SnatchOptions, SnatchResult, } from "./types.js";
+export { DOWNLOAD_CANCELLED_MESSAGE, isCancelledError } from "./cancellation.js";
+export { discardPausedDownload, pauseSnatchDownload, snatchBlob, snatchBlobToDisk, } from "./snatch.js";
+export { BlobServer, DEFAULT_RELEASE_AFTER_MS, serveBlobRequest, } from "./serve.js";
+export type { BlobServerOptions, ServedBlobInfo } from "./serve.js";
+export { createPrefetcher, Prefetcher } from "./prefetch.js";
+export type { PrefetchOptions } from "./prefetch.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/transfer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEjF,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,UAAU,EACV,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,UAAU,EACV,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/transfer/index.js

@@ -0,0 +1,4 @@
+export { DOWNLOAD_CANCELLED_MESSAGE, isCancelledError } from "./cancellation.js";
+export { discardPausedDownload, pauseSnatchDownload, snatchBlob, snatchBlobToDisk, } from "./snatch.js";
+export { BlobServer, DEFAULT_RELEASE_AFTER_MS, serveBlobRequest, } from "./serve.js";
+export { createPrefetcher, Prefetcher } from "./prefetch.js";

package/dist/transfer/prefetch.d.ts

@@ -0,0 +1,38 @@
+/** what one prefetch run needs to know how to do. */
+export interface PrefetchOptions<T> {
+    /** total budget consumed as items are selected for this run; selection
+     *  stops once the budget is exhausted (or the item list runs out). */
+    budget: number;
+    /** cost of fetching one item, subtracted from the budget as items are
+     *  selected. */
+    costOf(item: T): number;
+    /** fetch one selected item. */
+    fetchItem(item: T): Promise<void>;
+    /** how many items to fetch concurrently. default 3. */
+    concurrency?: number;
+    /** called once per item, when it is selected for this run (before any
+     *  fetching starts) - useful for a "pending" ui state. */
+    onPending?(item: T): void;
+    /** called once per item whose `onPending` fired, when its fetch settles
+     *  (success, failure, or superseded by a newer `run()` before it was
+     *  reached) - always paired with a prior `onPending` call. */
+    onSettled?(item: T): void;
+}
+/**
+ * a cancellable prefetch runner. calling `run()` again before a prior run
+ * finishes supersedes it: a run-counter check before every selection and
+ * batch step stops the superseded run from selecting or fetching anything
+ * further, without needing an `AbortController` threaded through
+ * `fetchItem` itself.
+ */
+export declare class Prefetcher<T> {
+    private runCounter;
+    /** fire-and-forget: start a new run over `items`, superseding any run
+     *  still in flight. */
+    run(items: T[], options: PrefetchOptions<T>): void;
+    private isCurrent;
+    private execute;
+}
+/** construct a fresh, independent prefetch runner. */
+export declare function createPrefetcher<T>(): Prefetcher<T>;
+//# sourceMappingURL=prefetch.d.ts.map

package/dist/transfer/prefetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch.d.ts","sourceRoot":"","sources":["../../src/transfer/prefetch.ts"],"names":[],"mappings":"AASA,qDAAqD;AACrD,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC;0EACsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf;oBACgB;IAChB,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;IACxB,+BAA+B;IAC/B,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;8DAC0D;IAC1D,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAC1B;;kEAE8D;IAC9D,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,UAAU,CAAC,CAAC;IACvB,OAAO,CAAC,UAAU,CAAK;IAEvB;2BACuB;IACvB,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI;IAKlD,OAAO,CAAC,SAAS;YAIH,OAAO;CA8BtB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAEnD"}

package/dist/transfer/prefetch.js

@@ -0,0 +1,61 @@
+// budget-limited, cancellable prefetch: select a prefix of "upcoming"
+// items whose cumulative cost fits a budget (e.g. seconds of playback,
+// bytes of storage), then fetch them in concurrent batches.
+//
+// the domain concept (what an item is, what it costs, how to fetch it)
+// stays with the caller via `costOf`/`fetchItem`; this module only owns
+// the budget selection, concurrency batching, and run-counter
+// cancellation.
+/**
+ * a cancellable prefetch runner. calling `run()` again before a prior run
+ * finishes supersedes it: a run-counter check before every selection and
+ * batch step stops the superseded run from selecting or fetching anything
+ * further, without needing an `AbortController` threaded through
+ * `fetchItem` itself.
+ */
+export class Prefetcher {
+    runCounter = 0;
+    /** fire-and-forget: start a new run over `items`, superseding any run
+     *  still in flight. */
+    run(items, options) {
+        const run = ++this.runCounter;
+        void this.execute(run, items, options);
+    }
+    isCurrent(run) {
+        return run === this.runCounter;
+    }
+    async execute(run, items, options) {
+        const concurrency = options.concurrency ?? 3;
+        let budget = options.budget;
+        const selected = [];
+        for (const item of items) {
+            if (!this.isCurrent(run))
+                return;
+            if (budget <= 0)
+                break;
+            budget -= options.costOf(item);
+            options.onPending?.(item);
+            selected.push(item);
+        }
+        for (let i = 0; i < selected.length; i += concurrency) {
+            if (!this.isCurrent(run)) {
+                for (const item of selected.slice(i))
+                    options.onSettled?.(item);
+                return;
+            }
+            const batch = selected.slice(i, i + concurrency);
+            await Promise.allSettled(batch.map(async (item) => {
+                try {
+                    await options.fetchItem(item);
+                }
+                finally {
+                    options.onSettled?.(item);
+                }
+            }));
+        }
+    }
+}
+/** construct a fresh, independent prefetch runner. */
+export function createPrefetcher() {
+    return new Prefetcher();
+}

package/dist/transfer/prefetch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prefetch.test.d.ts.map

package/dist/transfer/prefetch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch.test.d.ts","sourceRoot":"","sources":["../../src/transfer/prefetch.test.ts"],"names":[],"mappings":""}