@multiplatform.one/platform 7.10.0 → 7.15.0

package/src/config/devOrigin.ts

@@ -0,0 +1,45 @@
+import { devOriginSource } from "./devOriginSource";
+
+/**
+ * Where the running app learns the dev machine's address from.
+ *
+ * On native, `hostUri` is Expo's `Constants.expoConfig.hostUri`: the
+ * `host:port` the device fetched its manifest from, which @expo/cli fills in
+ * from the request's Host header. It is therefore the one address the device
+ * is already proven to reach, whatever the machine's LAN IP happens to be,
+ * and it is absent in a release build, where nothing points at localhost.
+ */
+export interface DevOriginSource {
+  isWeb: boolean;
+  hostUri?: string;
+}
+
+const loopbackOrigin = /^([a-z][a-z0-9+.-]*:\/\/)(localhost|127\.0\.0\.1)(?=[:/?#]|$)/i;
+
+/** The host part of a `host:port`, `scheme://host:port/path` or `[v6]:port` value. */
+export function devHostFromHostUri(hostUri: string | undefined): string | undefined {
+  if (!hostUri) return undefined;
+  const authority = hostUri.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "").split(/[/?#]/, 1)[0];
+  const host = authority.startsWith("[")
+    ? authority.slice(0, authority.indexOf("]") + 1)
+    : authority.split(":", 1)[0];
+  return host || undefined;
+}
+
+/**
+ * Point a loopback-configured origin at the dev machine on native.
+ *
+ * `http://localhost:8000` in .env means "the machine running the dev server"
+ * on every platform. In a browser that is the page host; on a simulator, an
+ * emulator or a phone it is the host the bundle came from, so the same .env
+ * serves all of them. Web, and anything without a hostUri, is returned as is.
+ *
+ * String-based on purpose: React Native's URL polyfill has no `hostname`
+ * setter, so a new-URL-and-assign rewrite silently no-ops on device.
+ */
+export function resolveDevOrigin(url: string, source: DevOriginSource = devOriginSource()): string {
+  if (source.isWeb) return url;
+  const host = devHostFromHostUri(source.hostUri);
+  if (!host) return url;
+  return url.replace(loopbackOrigin, `$1${host}`);
+}

package/src/config/devOriginSource.native.ts

@@ -0,0 +1,9 @@
+import constants from "expo-constants";
+import type { DevOriginSource } from "./devOrigin";
+
+export function devOriginSource(): DevOriginSource {
+  return {
+    isWeb: false,
+    hostUri: constants.expoConfig?.hostUri ?? constants.manifest2?.extra?.expoGo?.debuggerHost,
+  };
+}

package/src/config/devOriginSource.ts

@@ -0,0 +1,5 @@
+import type { DevOriginSource } from "./devOrigin";
+
+export function devOriginSource(): DevOriginSource {
+  return { isWeb: true };
+}

package/src/config/index.ts

@@ -4,4 +4,5 @@ const config = new Config();
 
 export { config };
 export * from "./config";
+export * from "./devOrigin";
 export * from "./runtimeConfig";

package/src/file/index.ts

@@ -0,0 +1,3 @@
+export { saveFile } from "./saveFile";
+export { FileSaveError } from "./types";
+export type { FileSaveOptions, FileSaveResult, FileSaveErrorCode, WrittenFile } from "./types";

package/src/file/saveFile.native.spec.ts

@@ -0,0 +1,245 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const native = vi.hoisted(() => ({
+  platform: { isIos: false, isAndroid: true },
+  pick: vi.fn(),
+  loaded: vi.fn(),
+}));
+vi.mock("../platform", () => ({ platform: native.platform }));
+
+describe("native byte save (native boundary modeled)", () => {
+  const options = () => ({
+    bytes: new Uint8Array([0, 255, 13, 10]),
+    filename: "café.bin",
+    mimeType: "application/octet-stream; charset=binary",
+  });
+  let file: {
+    uri: string;
+    name: string;
+    write: ReturnType<typeof vi.fn>;
+    delete: ReturnType<typeof vi.fn>;
+  };
+  let directory: {
+    uri: string;
+    createFile: ReturnType<typeof vi.fn>;
+    delete: ReturnType<typeof vi.fn>;
+  };
+  beforeEach(() => {
+    vi.resetModules();
+    vi.doMock("expo-file-system", () => {
+      native.loaded();
+      return { Directory: { pickDirectoryAsync: native.pick } };
+    });
+    vi.clearAllMocks();
+    native.platform.isIos = false;
+    native.platform.isAndroid = true;
+    file = {
+      uri: "content://provider/child-42",
+      name: "café (1).bin",
+      write: vi.fn(),
+      delete: vi.fn(),
+    };
+    directory = {
+      uri: "content://provider/tree/selected",
+      createFile: vi.fn(() => file),
+      delete: vi.fn(),
+    };
+    native.pick.mockReset().mockResolvedValue(directory);
+  });
+  const api = () => import("./saveFile.native");
+
+  it("loads FileSystem only on invocation and writes the exact snapshot to the provider child", async () => {
+    const { saveFile } = await api();
+    expect(native.loaded).not.toHaveBeenCalled();
+    let choose!: (value: typeof directory) => void;
+    native.pick.mockReturnValue(
+      new Promise((resolve) => {
+        choose = resolve;
+      }),
+    );
+    const input = options();
+    input.bytes = new Uint8Array([99, 0, 255, 13, 10, 88]).subarray(1, 5);
+    const pending = saveFile(input);
+    input.bytes.fill(8);
+    input.filename = "changed-after-request.bin";
+    await vi.waitFor(() => expect(native.pick).toHaveBeenCalledOnce());
+    choose(directory);
+    await expect(pending).resolves.toEqual({
+      status: "written",
+      uri: file.uri,
+      requestedFilename: "café.bin",
+      byteLength: 4,
+    });
+    expect(directory.createFile).toHaveBeenCalledExactlyOnceWith(
+      "café.bin",
+      "application/octet-stream",
+    );
+    expect(Array.from(file.write.mock.calls[0][0])).toEqual([0, 255, 13, 10]);
+    expect(file.delete).not.toHaveBeenCalled();
+    expect(directory.delete).not.toHaveBeenCalled();
+  });
+
+  it("reports the iOS file-URI name separately from the requested name, including empty files", async () => {
+    native.platform.isIos = true;
+    native.platform.isAndroid = false;
+    directory.uri = "file:///selected/";
+    file.uri = "file:///selected/caf%C3%A9%20(1).bin";
+    const { saveFile } = await api();
+    await expect(saveFile({ ...options(), bytes: new Uint8Array() })).resolves.toEqual({
+      status: "written",
+      uri: file.uri,
+      requestedFilename: "café.bin",
+      filename: "café (1).bin",
+      byteLength: 0,
+    });
+    expect(file.write).toHaveBeenCalledWith(new Uint8Array());
+    expect(file.delete).not.toHaveBeenCalled();
+  });
+
+  it("omits an opaque Android document ID without reading it as a filename", async () => {
+    file.uri = "content://example.documents/tree/root/document/42";
+    const readName = vi.fn(() => "42");
+    Object.defineProperty(file, "name", { get: readName });
+    const input = { ...options(), filename: "fixture.bin" };
+    const { saveFile } = await api();
+    await expect(saveFile(input)).resolves.toEqual({
+      status: "written",
+      uri: file.uri,
+      requestedFilename: "fixture.bin",
+      byteLength: 4,
+    });
+    expect(readName).not.toHaveBeenCalled();
+    expect(directory.createFile).toHaveBeenCalledExactlyOnceWith(
+      "fixture.bin",
+      "application/octet-stream",
+    );
+    expect(file.write).toHaveBeenCalledExactlyOnceWith(new Uint8Array([0, 255, 13, 10]));
+    expect(file.delete).not.toHaveBeenCalled();
+    expect(directory.delete).not.toHaveBeenCalled();
+  });
+
+  it("only reports an iOS filename when the created file has a file URI", async () => {
+    native.platform.isIos = true;
+    native.platform.isAndroid = false;
+    directory.uri = "file:///selected/";
+    const readName = vi.fn(() => "child-42");
+    Object.defineProperty(file, "name", { get: readName });
+    const { saveFile } = await api();
+    await expect(saveFile(options())).resolves.toEqual({
+      status: "written",
+      uri: file.uri,
+      requestedFilename: "café.bin",
+      byteLength: 4,
+    });
+    expect(readName).not.toHaveBeenCalled();
+    expect(file.write).toHaveBeenCalledOnce();
+    expect(file.delete).not.toHaveBeenCalled();
+  });
+
+  it.each(["ERR_PICKER_CANCELLED", "ERR_FILE_PICKING_CANCELLED"])(
+    "reports %s as not saved without inventing cancel/refusal distinction",
+    async (code) => {
+      const { saveFile } = await api();
+      native.pick.mockRejectedValueOnce({ code });
+      await expect(saveFile(options())).resolves.toEqual({
+        status: "not-saved",
+        reason: "cancelled-or-refused",
+      });
+      expect(directory.createFile).not.toHaveBeenCalled();
+      expect(file.write).not.toHaveBeenCalled();
+      await expect(saveFile(options())).resolves.toMatchObject({ status: "written" });
+      expect(file.write).toHaveBeenCalledOnce();
+    },
+  );
+
+  it.each([
+    { code: "ERR_ACCESS_DENIED" },
+    new Error("User cancelled"),
+    { code: "ERR_PICKER_CANCELLED_EXTRA" },
+  ])("preserves non-cancellation picker failures: %j", async (cause) => {
+    native.pick.mockRejectedValue(cause);
+    const { saveFile } = await api();
+    await expect(saveFile(options())).rejects.toMatchObject({ code: "picker-failed", cause });
+    expect(directory.createFile).not.toHaveBeenCalled();
+  });
+
+  it("rejects overlapping requests and accepts a retry once the picker settles", async () => {
+    let choose!: (value: typeof directory) => void;
+    native.pick.mockReturnValueOnce(
+      new Promise((resolve) => {
+        choose = resolve;
+      }),
+    );
+    const { saveFile } = await api();
+    const first = saveFile(options());
+    await expect(saveFile(options())).rejects.toMatchObject({ code: "busy" });
+    await vi.waitFor(() => expect(native.pick).toHaveBeenCalledOnce());
+    choose(directory);
+    await expect(first).resolves.toMatchObject({ status: "written" });
+    await expect(saveFile(options())).resolves.toMatchObject({ status: "written" });
+  });
+
+  it("rejects invalid inputs before loading native code or opening the picker", async () => {
+    const { saveFile } = await api();
+    await expect(saveFile({ ...options(), filename: "../escape" })).rejects.toMatchObject({
+      code: "invalid-input",
+    });
+    expect(native.loaded).not.toHaveBeenCalled();
+    expect(native.pick).not.toHaveBeenCalled();
+  });
+
+  it.each(["file:///private/not-saf", "https://example.test", ""])(
+    "refuses unexpected Android directory URI %j",
+    async (uri) => {
+      directory.uri = uri;
+      const { saveFile } = await api();
+      await expect(saveFile(options())).rejects.toMatchObject({ code: "picker-failed" });
+      expect(directory.createFile).not.toHaveBeenCalled();
+    },
+  );
+
+  it("refuses unsupported native hosts before loading FileSystem", async () => {
+    native.platform.isAndroid = false;
+    const { saveFile } = await api();
+    await expect(saveFile(options())).rejects.toMatchObject({ code: "unavailable" });
+    expect(native.loaded).not.toHaveBeenCalled();
+  });
+
+  it("does not delete anything when creation or a duplicate name is refused", async () => {
+    const cause = new Error("already exists");
+    directory.createFile.mockImplementation(() => {
+      throw cause;
+    });
+    const { saveFile } = await api();
+    await expect(saveFile(options())).rejects.toMatchObject({ code: "write-failed", cause });
+    expect(file.write).not.toHaveBeenCalled();
+    expect(file.delete).not.toHaveBeenCalled();
+    expect(directory.delete).not.toHaveBeenCalled();
+  });
+
+  it.each([false, true])(
+    "deletes only its new child on write failure and preserves cleanup failure (%s)",
+    async (cleanupFails) => {
+      const cause = new Error("storage full");
+      const cleanupError = new Error("delete refused");
+      file.write.mockImplementationOnce(() => {
+        throw cause;
+      });
+      if (cleanupFails)
+        file.delete.mockImplementation(() => {
+          throw cleanupError;
+        });
+      const { saveFile } = await api();
+      await expect(saveFile(options())).rejects.toMatchObject({
+        code: "write-failed",
+        cause,
+        cleanupError: cleanupFails ? cleanupError : undefined,
+      });
+      expect(file.write).toHaveBeenCalledOnce();
+      expect(file.delete).toHaveBeenCalledOnce();
+      expect(directory.delete).not.toHaveBeenCalled();
+      await expect(saveFile(options())).resolves.toMatchObject({ status: "written" });
+      expect(file.delete).toHaveBeenCalledOnce();
+    },
+  );
+});

package/src/file/saveFile.native.ts

@@ -0,0 +1,83 @@
+import type { Directory, File } from "expo-file-system";
+import { platform } from "../platform";
+import { FileSaveError, type FileSaveOptions, type FileSaveResult, prepareFileSave } from "./types";
+
+let busy = false;
+
+export async function saveFile(options: FileSaveOptions): Promise<FileSaveResult> {
+  const input = prepareFileSave(options);
+  if (!platform.isIos && !platform.isAndroid) {
+    throw new FileSaveError(
+      "unavailable",
+      "Directory file saving is unavailable on this platform.",
+    );
+  }
+  if (busy) throw new FileSaveError("busy", "Another file save is in progress.");
+  busy = true;
+  try {
+    let fileSystem: typeof import("expo-file-system");
+    try {
+      fileSystem = await import("expo-file-system");
+      if (typeof fileSystem.Directory?.pickDirectoryAsync !== "function") {
+        throw new Error("The native FileSystem directory picker is unavailable.");
+      }
+    } catch (cause) {
+      throw new FileSaveError(
+        "unavailable",
+        "This native build cannot save files to a directory.",
+        { cause },
+      );
+    }
+
+    let directory: Directory;
+    try {
+      directory = await fileSystem.Directory.pickDirectoryAsync();
+      const scheme = platform.isAndroid ? "content://" : "file://";
+      if (!directory.uri.startsWith(scheme) || directory.uri.length <= scheme.length) {
+        throw new Error("The picker returned an unsupported directory URI.");
+      }
+    } catch (cause) {
+      if (
+        typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        (cause.code === "ERR_PICKER_CANCELLED" || cause.code === "ERR_FILE_PICKING_CANCELLED")
+      ) {
+        // iOS also uses this code when security-scoped directory access is refused.
+        return { status: "not-saved", reason: "cancelled-or-refused" };
+      }
+      throw new FileSaveError("picker-failed", "A writable directory could not be selected.", {
+        cause,
+      });
+    }
+
+    let file: File | undefined;
+    try {
+      file = directory.createFile(input.filename, input.nativeMimeType);
+      const uri = file.uri;
+      // Android content URIs can contain opaque IDs instead of provider display names.
+      const filename = platform.isIos && uri.startsWith("file://") ? { filename: file.name } : {};
+      file.write(input.bytes);
+      return {
+        status: "written",
+        uri,
+        requestedFilename: input.filename,
+        ...filename,
+        byteLength: input.bytes.byteLength,
+      };
+    } catch (cause) {
+      let cleanupError: unknown;
+      try {
+        file?.delete();
+      } catch (error) {
+        cleanupError = error;
+      }
+      throw new FileSaveError("write-failed", "The file could not be written.", {
+        cause,
+        cleanupError,
+      });
+    }
+  } finally {
+    busy = false;
+  }
+}

package/src/file/saveFile.spec.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { FileSaveError, saveFile } from "./index";
+
+describe("web byte save", () => {
+  const options = () => ({
+    bytes: new Uint8Array([0, 255, 13, 10]),
+    filename: "café.bin",
+    mimeType: "application/octet-stream",
+  });
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+    vi.spyOn(URL, "createObjectURL").mockReturnValue("blob:fixture");
+    vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.runAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("requests a download with the exact byte view and filename", async () => {
+    const input = options();
+    input.bytes = new Uint8Array([99, 0, 255, 13, 10, 88]).subarray(1, 5);
+    vi.mocked(HTMLAnchorElement.prototype.click).mockImplementation(
+      function (this: HTMLAnchorElement) {
+        expect(this.download).toBe("café.bin");
+      },
+    );
+    const result = saveFile(input);
+    input.bytes.fill(7);
+    await expect(result).resolves.toEqual({ status: "download-requested" });
+    const blob = vi.mocked(URL.createObjectURL).mock.calls[0][0] as Blob;
+    expect(Array.from(new Uint8Array(await blob.arrayBuffer()))).toEqual([0, 255, 13, 10]);
+    expect(blob.type).toBe("application/octet-stream");
+    expect(HTMLAnchorElement.prototype.click).toHaveBeenCalledOnce();
+  });
+
+  it("preserves UTF-8 bytes and MIME parameters, including an empty file", async () => {
+    const bytes = new TextEncoder().encode("café ☕\n");
+    await saveFile({ ...options(), bytes, mimeType: "text/plain; charset=utf-8" });
+    const blob = vi.mocked(URL.createObjectURL).mock.calls[0][0] as Blob;
+    expect(await blob.text()).toBe("café ☕\n");
+    expect(blob.type).toBe("text/plain; charset=utf-8");
+    await saveFile({ ...options(), bytes: new Uint8Array() });
+    expect((vi.mocked(URL.createObjectURL).mock.calls[1][0] as Blob).size).toBe(0);
+  });
+
+  it.each(["", "  ", ".", "..", "a/b", "a\\b", "a\u0000b", "a\nb", "a\u007fb"])(
+    "rejects filename %j before allocating resources",
+    async (filename) => {
+      await expect(saveFile({ ...options(), filename })).rejects.toMatchObject({
+        code: "invalid-input",
+      });
+      expect(URL.createObjectURL).not.toHaveBeenCalled();
+      expect(HTMLAnchorElement.prototype.click).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["", "text", "text/", "text /plain", "text/plain\n"])(
+    "rejects invalid MIME %j",
+    async (mimeType) => {
+      await expect(saveFile({ ...options(), mimeType })).rejects.toMatchObject({
+        code: "invalid-input",
+      });
+      expect(URL.createObjectURL).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([null, {}, { ...options(), bytes: [1, 2] }])(
+    "rejects malformed input %j",
+    async (input) => {
+      await expect(saveFile(input as never)).rejects.toBeInstanceOf(FileSaveError);
+      await expect(saveFile(input as never)).rejects.toMatchObject({ code: "invalid-input" });
+      expect(URL.createObjectURL).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["document", "Blob", "URL"])(
+    "reports an unavailable %s capability",
+    async (capability) => {
+      vi.stubGlobal(capability, undefined);
+      await expect(saveFile(options())).rejects.toMatchObject({ code: "unavailable" });
+    },
+  );
+
+  it("reports activation failure with its original cause and cleans resources", async () => {
+    const cause = new Error("download refused");
+    vi.mocked(HTMLAnchorElement.prototype.click).mockImplementation(() => {
+      throw cause;
+    });
+    await expect(saveFile(options())).rejects.toMatchObject({ code: "write-failed", cause });
+    expect(document.querySelector("a")).toBeNull();
+    vi.advanceTimersByTime(60_000);
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith("blob:fixture");
+  });
+});

package/src/file/saveFile.ts

@@ -0,0 +1,25 @@
+import { downloadBlob } from "../utils/downloadFile";
+import { FileSaveError, type FileSaveOptions, type FileSaveResult, prepareFileSave } from "./types";
+
+export async function saveFile(options: FileSaveOptions): Promise<FileSaveResult> {
+  const input = prepareFileSave(options);
+  if (
+    typeof document === "undefined" ||
+    !document.body ||
+    typeof Blob === "undefined" ||
+    typeof URL === "undefined" ||
+    typeof URL.createObjectURL !== "function" ||
+    typeof URL.revokeObjectURL !== "function" ||
+    !("download" in document.createElement("a"))
+  ) {
+    throw new FileSaveError("unavailable", "Browser file downloads are unavailable.");
+  }
+  try {
+    downloadBlob(new Blob([input.bytes], { type: input.mimeType }), input.filename);
+  } catch (cause) {
+    throw new FileSaveError("write-failed", "The browser download could not be requested.", {
+      cause,
+    });
+  }
+  return { status: "download-requested" };
+}

package/src/file/saveFile.unavailable.native.spec.ts

@@ -0,0 +1,24 @@
+import { expect, it, vi } from "vitest";
+
+const boundary = vi.hoisted(() => ({
+  loaded: vi.fn(),
+  cause: new Error("Native FileSystem is absent"),
+}));
+vi.mock("../platform", () => ({ platform: { isAndroid: true, isIos: false } }));
+vi.mock("expo-file-system", () => {
+  boundary.loaded();
+  throw boundary.cause;
+});
+
+it("keeps a missing native module out of import-time execution and rejects invocation", async () => {
+  const { saveFile } = await import("./saveFile.native");
+  expect(boundary.loaded).not.toHaveBeenCalled();
+  const input = {
+    bytes: new Uint8Array([42]),
+    filename: "fixture.bin",
+    mimeType: "application/octet-stream",
+  };
+  await expect(saveFile(input)).rejects.toMatchObject({ code: "unavailable" });
+  expect(boundary.loaded).toHaveBeenCalledOnce();
+  await expect(saveFile(input)).rejects.toMatchObject({ code: "unavailable" });
+});

package/src/file/types.ts

@@ -0,0 +1,74 @@
+export interface FileSaveOptions {
+  bytes: Uint8Array;
+  filename: string;
+  mimeType: string;
+}
+
+export type WrittenFile = {
+  status: "written";
+  uri: string;
+  requestedFilename: string;
+  filename?: string;
+  byteLength: number;
+};
+
+export type FileSaveResult =
+  | WrittenFile
+  | { status: "download-requested" }
+  | { status: "not-saved"; reason: "cancelled-or-refused" };
+
+export type FileSaveErrorCode =
+  | "invalid-input"
+  | "unavailable"
+  | "busy"
+  | "picker-failed"
+  | "write-failed";
+
+export class FileSaveError extends Error {
+  readonly code: FileSaveErrorCode;
+  readonly cleanupError?: unknown;
+
+  constructor(
+    code: FileSaveErrorCode,
+    message: string,
+    options?: { cause?: unknown; cleanupError?: unknown },
+  ) {
+    super(message, options);
+    this.name = "FileSaveError";
+    this.code = code;
+    this.cleanupError = options?.cleanupError;
+  }
+}
+
+function hasControlCharacters(value: string) {
+  return Array.from(value).some(
+    (character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
+  );
+}
+
+export function prepareFileSave(options: FileSaveOptions) {
+  if (
+    !options ||
+    !(options.bytes instanceof Uint8Array) ||
+    typeof options.filename !== "string" ||
+    !options.filename.trim() ||
+    options.filename === "." ||
+    options.filename === ".." ||
+    /[/\\]/.test(options.filename) ||
+    hasControlCharacters(options.filename) ||
+    typeof options.mimeType !== "string" ||
+    hasControlCharacters(options.mimeType)
+  ) {
+    throw new FileSaveError("invalid-input", "Provide bytes, a single filename and a MIME type.");
+  }
+  const nativeMimeType = options.mimeType.split(";", 1)[0].trim();
+  if (!/^[\w!#$%&'*+.^`|~-]+\/[\w!#$%&'*+.^`|~-]+$/.test(nativeMimeType)) {
+    throw new FileSaveError("invalid-input", "Provide a MIME type with a type and subtype.");
+  }
+  return {
+    bytes: Uint8Array.from(options.bytes),
+    filename: options.filename,
+    mimeType: options.mimeType,
+    nativeMimeType,
+  };
+}

package/src/utils/downloadFile.spec.ts

@@ -0,0 +1,54 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { downloadBlob, downloadFile } from "./downloadFile";
+
+describe("synchronous download helpers", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => {
+    vi.runAllTimers();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    document.body.replaceChildren();
+  });
+
+  it("activates the named URL and returns void synchronously", () => {
+    const click = vi
+      .spyOn(HTMLAnchorElement.prototype, "click")
+      .mockImplementation(function (this: HTMLAnchorElement) {
+        expect(this.isConnected).toBe(true);
+        expect(this.href).toBe("https://example.test/file");
+        expect(this.download).toBe("café.txt");
+      });
+    expect(downloadFile("https://example.test/file", "café.txt")).toBeUndefined();
+    expect(click).toHaveBeenCalledOnce();
+    expect(document.querySelector("a")).toBeNull();
+  });
+
+  it("removes the anchor when activation throws", () => {
+    const failure = new Error("activation refused");
+    vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {
+      throw failure;
+    });
+    expect(() => downloadFile("https://example.test/file", "file.txt")).toThrow(failure);
+    expect(document.querySelector("a")).toBeNull();
+  });
+
+  it.each([false, true])(
+    "releases a Blob URL after activation, even if it throws (%s)",
+    (throws) => {
+      const blob = new Blob(["fixture"]);
+      const create = vi.spyOn(URL, "createObjectURL").mockReturnValue("blob:fixture");
+      const revoke = vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {});
+      vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {
+        expect(revoke).not.toHaveBeenCalled();
+        if (throws) throw new Error("activation refused");
+      });
+      if (throws) expect(() => downloadBlob(blob, "fixture.txt")).toThrow("activation refused");
+      else expect(downloadBlob(blob, "fixture.txt")).toBeUndefined();
+      expect(create).toHaveBeenCalledWith(blob);
+      expect(document.querySelector("a")).toBeNull();
+      expect(revoke).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(60_000);
+      expect(revoke).toHaveBeenCalledExactlyOnceWith("blob:fixture");
+    },
+  );
+});