winui-svelte 0.0.4 → 0.0.6

package/src/downloads/download-query.ts

@@ -0,0 +1,204 @@
+import type { DownloadItem, DownloadQuery } from "./download-types.ts";
+
+const DEFAULT_LIMIT = 1000;
+const DESCENDING_PREFIX = "-";
+
+const EXACT_FIELDS = [
+  "id",
+  "url",
+  "finalUrl",
+  "filename",
+  "mime",
+  "startTime",
+  "endTime",
+  "state",
+  "paused",
+  "error",
+  "bytesReceived",
+  "totalBytes",
+  "fileSize",
+  "exists"
+] as const;
+
+function millisecondsOf(time: string | number) {
+  return new Date(time).getTime();
+}
+
+function includesTerm({ item, term }: {
+  item: DownloadItem;
+  term: string;
+}) {
+  const needle = term.toLowerCase();
+  return `${item.filename}\n${item.url}`.toLowerCase().includes(needle);
+}
+
+function matchesTerms({ item, terms }: {
+  item: DownloadItem;
+  terms: readonly string[];
+}) {
+  return terms.every(term => {
+    const isExcluded = term.startsWith(DESCENDING_PREFIX);
+    return isExcluded ? !includesTerm({
+      item,
+      term: term.slice(1)
+    }) : includesTerm({
+      item,
+      term
+    });
+  });
+}
+
+function isBefore({ time, limit }: {
+  time: string | undefined;
+  limit: string | number | undefined;
+}) {
+  const isUnbounded = limit === undefined;
+  if (isUnbounded) {
+    return true;
+  }
+
+  return time !== undefined && millisecondsOf(time) < millisecondsOf(limit);
+}
+
+function isAfter({ time, limit }: {
+  time: string | undefined;
+  limit: string | number | undefined;
+}) {
+  const isUnbounded = limit === undefined;
+  if (isUnbounded) {
+    return true;
+  }
+
+  return time !== undefined && millisecondsOf(time) > millisecondsOf(limit);
+}
+
+function matchesPattern({ text, pattern }: {
+  text: string;
+  pattern: string | undefined;
+}) {
+  return pattern === undefined || new RegExp(pattern, "u").test(text);
+}
+
+function matchesExactFields({ item, query }: {
+  item: DownloadItem;
+  query: DownloadQuery;
+}) {
+  return EXACT_FIELDS.every(field => query[field] === undefined || query[field] === item[field]);
+}
+
+function matchesRanges({ item, query }: {
+  item: DownloadItem;
+  query: DownloadQuery;
+}) {
+  const { totalBytesGreater, totalBytesLess } = query;
+  const isGreaterEnough = totalBytesGreater === undefined || item.totalBytes > totalBytesGreater;
+  const isLessEnough = totalBytesLess === undefined || item.totalBytes < totalBytesLess;
+  const isStartInside = isBefore({
+    time: item.startTime,
+    limit: query.startedBefore
+  }) && isAfter({
+    time: item.startTime,
+    limit: query.startedAfter
+  });
+  const isEndInside = isBefore({
+    time: item.endTime,
+    limit: query.endedBefore
+  }) && isAfter({
+    time: item.endTime,
+    limit: query.endedAfter
+  });
+  return isGreaterEnough && isLessEnough && isStartInside && isEndInside;
+}
+
+function matchesQuery({ item, query }: {
+  item: DownloadItem;
+  query: DownloadQuery;
+}) {
+  const isTextMatch = matchesTerms({
+    item,
+    terms: query.query ?? []
+  }) && matchesPattern({
+    text: item.filename,
+    pattern: query.filenameRegex
+  }) && matchesPattern({
+    text: item.url,
+    pattern: query.urlRegex
+  }) && matchesPattern({
+    text: item.finalUrl,
+    pattern: query.finalUrlRegex
+  });
+  return isTextMatch && matchesExactFields({
+    item,
+    query
+  }) && matchesRanges({
+    item,
+    query
+  });
+}
+
+function orderOf({ left, right }: {
+  left: unknown;
+  right: unknown;
+}) {
+  const isNumbers = typeof left === "number" && typeof right === "number";
+  const isStrings = typeof left === "string" && typeof right === "string";
+  const isOrdered = isNumbers || isStrings;
+  if (!isOrdered) {
+    return 0;
+  }
+
+  return left < right ? -1 : Number(left > right);
+}
+
+function compareBy({ first, second, field }: {
+  first: DownloadItem;
+  second: DownloadItem;
+  field: string;
+}) {
+  const isDescending = field.startsWith(DESCENDING_PREFIX);
+  const key = isDescending ? field.slice(1) : field;
+  const firstFields: Record<string, unknown> = { ...first };
+  const secondFields: Record<string, unknown> = { ...second };
+  const left = firstFields[key];
+  const right = secondFields[key];
+  const order = orderOf({
+    left,
+    right
+  });
+  return isDescending ? -order : order;
+}
+
+/**
+ * The items a query selects, as `chrome.downloads.search` selects them: every
+ * given field must match, `query` terms are searched in the file name and the
+ * address (a leading `-` excludes), `orderBy` sorts and `limit` cuts.
+ *
+ * @param options - The items, oldest first, and the query.
+ * @returns The matching items in the requested order.
+ */
+export function selectItems({ items, query }: {
+  items: readonly DownloadItem[];
+  query: DownloadQuery;
+}) {
+  const matching = items.filter(item => matchesQuery({
+    item,
+    query
+  }));
+  const orderBy = query.orderBy ?? [];
+  const sorted = matching.toSorted((first, second) => {
+    for (const field of orderBy) {
+      const order = compareBy({
+        first,
+        second,
+        field
+      });
+      const isDecided = order !== 0;
+      if (isDecided) {
+        return order;
+      }
+    }
+
+    return 0;
+  });
+  return sorted.slice(0, query.limit ?? DEFAULT_LIMIT);
+}

package/src/downloads/download-record.ts

@@ -0,0 +1,176 @@
+import type { ChromeDownloadOptions, DownloadDelta, DownloadItem, InterruptReason } from "./download-types.ts";
+import { DownloadState } from "./download-types.ts";
+import type { taskbarReporter } from "./taskbar-progress.ts";
+
+/** What a caller of `pause` or `cancel` asked for, so the transfer's abort is read the right way. */
+export const DownloadIntent = {
+  PAUSE: "pause",
+  CANCEL: "cancel"
+} as const;
+/** One of the values of `DownloadIntent`. */
+export type DownloadIntent = (typeof DownloadIntent)[keyof typeof DownloadIntent];
+
+/** A `DownloadItem` with every property present, so an update can clear `error` and `endTime`. */
+export interface StoredItem extends Omit<DownloadItem, "endTime" | "error"> {
+  readonly endTime: string | undefined;
+  readonly error: InterruptReason | undefined;
+}
+
+/** Everything the downloads object keeps about one download. */
+export interface DownloadRecord {
+  item: StoredItem;
+  readonly options: ChromeDownloadOptions;
+  readonly report: ReturnType<typeof taskbarReporter>;
+
+  /** Where the bytes arrive: the final path plus ".part", or the final path itself when the user picked it. */
+  partialPath: string | undefined;
+  finalPath: string | undefined;
+  intent: DownloadIntent | undefined;
+  controller: AbortController;
+  running: Promise<void>;
+}
+
+/**
+ * The `DownloadItem` a listener or a search result sees.
+ *
+ * @param stored - The record's item.
+ * @returns A copy without the properties that are not set.
+ */
+export function publicItem(stored: StoredItem) {
+  const { endTime, error, ...rest } = stored;
+  return {
+    ...rest,
+    ...endTime !== undefined && {
+      endTime
+    },
+    ...error !== undefined && {
+      error
+    }
+  } satisfies DownloadItem;
+}
+
+/**
+ * What changed between two states of a download, as `onChanged` reports it.
+ *
+ * @param options - The item before and after.
+ * @returns The delta, which holds only `id` when nothing changed.
+ */
+export function deltaOf({ before, after }: {
+  before: StoredItem;
+  after: StoredItem;
+}) {
+  return {
+    id: after.id,
+    ...before.url !== after.url && {
+      url: {
+        previous: before.url,
+        current: after.url
+      }
+    },
+    ...before.finalUrl !== after.finalUrl && {
+      finalUrl: {
+        previous: before.finalUrl,
+        current: after.finalUrl
+      }
+    },
+    ...before.filename !== after.filename && {
+      filename: {
+        previous: before.filename,
+        current: after.filename
+      }
+    },
+    ...before.mime !== after.mime && {
+      mime: {
+        previous: before.mime,
+        current: after.mime
+      }
+    },
+    ...before.endTime !== after.endTime && {
+      endTime: {
+        previous: before.endTime,
+        current: after.endTime
+      }
+    },
+    ...before.state !== after.state && {
+      state: {
+        previous: before.state,
+        current: after.state
+      }
+    },
+    ...before.canResume !== after.canResume && {
+      canResume: {
+        previous: before.canResume,
+        current: after.canResume
+      }
+    },
+    ...before.paused !== after.paused && {
+      paused: {
+        previous: before.paused,
+        current: after.paused
+      }
+    },
+    ...before.error !== after.error && {
+      error: {
+        previous: before.error,
+        current: after.error
+      }
+    },
+    ...before.bytesReceived !== after.bytesReceived && {
+      bytesReceived: {
+        previous: before.bytesReceived,
+        current: after.bytesReceived
+      }
+    },
+    ...before.totalBytes !== after.totalBytes && {
+      totalBytes: {
+        previous: before.totalBytes,
+        current: after.totalBytes
+      }
+    },
+    ...before.fileSize !== after.fileSize && {
+      fileSize: {
+        previous: before.fileSize,
+        current: after.fileSize
+      }
+    },
+    ...before.exists !== after.exists && {
+      exists: {
+        previous: before.exists,
+        current: after.exists
+      }
+    }
+  } satisfies DownloadDelta;
+}
+
+/**
+ * The item of a download that has just been asked for.
+ *
+ * @param options - Its id, address and start time.
+ * @returns The item, in progress with nothing received.
+ */
+export function newItem({ id, url, startTime }: {
+  id: number;
+  url: string;
+  startTime: string;
+}) {
+  return {
+    id,
+    url,
+    finalUrl: url,
+    referrer: "",
+    filename: "",
+    incognito: false,
+    danger: "safe",
+    mime: "",
+    startTime,
+    endTime: undefined,
+    state: DownloadState.IN_PROGRESS,
+    paused: false,
+    canResume: false,
+    error: undefined,
+    bytesReceived: 0,
+    totalBytes: -1,
+    fileSize: -1,
+    exists: false
+  } satisfies StoredItem;
+}

package/src/downloads/download-target.ts

@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const FALLBACK_NAME = "download";
+const INVALID_CHARACTERS = /[<>:"|?*\u0000-\u001F]/u;
+const EXTENDED_NAME = /filename\*\s*=\s*(?:utf-8|UTF-8)''([^;]+)/u;
+const QUOTED_NAME = /filename\s*=\s*"([^"]+)"/u;
+const PLAIN_NAME = /filename\s*=\s*([^;]+)/u;
+
+function decoded(text: string) {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+    return text;
+  }
+}
+
+function dispositionName(header: string | null) {
+  const match = EXTENDED_NAME.exec(header ?? "") ?? QUOTED_NAME.exec(header ?? "") ?? PLAIN_NAME.exec(header ?? "");
+  const name = match?.[1];
+  return name === undefined ? undefined : path.basename(decoded(name.trim()));
+}
+
+function addressName(address: string) {
+  const name = path.posix.basename(new URL(address).pathname);
+  return name === "" ? undefined : decoded(name);
+}
+
+function cleaned(name: string) {
+  return name.replaceAll(/[<>:"|?*\\/\u0000-\u001F]/gu, "_");
+}
+
+/**
+ * Checks that `DownloadOptions.filename` stays inside the downloads folder, as
+ * Chrome requires: relative, no `..`, no drive, no characters Windows forbids.
+ *
+ * @param filename - The name as the caller gave it.
+ * @throws {Error} When it would leave the folder or is not a valid name.
+ */
+export function assertRelativeFilename(filename: string) {
+  const segments = filename.split(/[\\/]/u);
+  const isEscaping = path.isAbsolute(filename) || /^[a-z]:/iu.test(filename) || segments.includes("..");
+  const isInvalid = isEscaping || segments.some(segment => INVALID_CHARACTERS.test(segment) || segment === "");
+  if (isInvalid) {
+    throw new Error(`Invalid filename: ${filename}`);
+  }
+}
+
+/**
+ * The name a download is saved under: the caller's, else the server's
+ * `Content-Disposition`, else the last part of the address.
+ *
+ * @param options - The caller's name, the response headers and the address.
+ * @returns A file name, without folders when it is not the caller's.
+ */
+export function suggestedName({ filename, disposition, address }: {
+  filename: string | undefined;
+  disposition: string | null;
+  address: string;
+}) {
+  return filename ?? cleaned(dispositionName(disposition) ?? addressName(address) ?? FALLBACK_NAME);
+}
+
+/**
+ * A path that no file uses yet: the given one, else with " (1)", " (2)" and so
+ * on before the extension, as a browser numbers a repeated download.
+ *
+ * @param location - The wanted path.
+ * @returns A free path.
+ */
+export function uniquePath(location: string) {
+  const { dir, name, ext } = path.parse(location);
+  let candidate = location;
+  for (let attempt = 1; existsSync(candidate); attempt += 1) {
+    candidate = path.join(dir, `${name} (${attempt})${ext}`);
+  }
+
+  return candidate;
+}

package/src/downloads/download-transfer.ts

@@ -0,0 +1,160 @@
+import type { DownloadRecord, StoredItem } from "./download-record.ts";
+import { suggestedName, uniquePath } from "./download-target.ts";
+import { DownloadState, FilenameConflictAction } from "./download-types.ts";
+import type { DownloadResponse } from "./fetch-to-file.ts";
+import { requestDownload, streamToFile } from "./fetch-to-file.ts";
+import { FileSystemFileHandle } from "#src/web-apis/file-system.js";
+import { TaskbarProgressState } from "#src/window/taskbar-calls.js";
+import { mkdir, rename, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** What a transfer needs from the downloads object that runs it. */
+export interface TransferContext {
+  /** The folder a relative `filename` is inside. */
+  readonly directory: string;
+  readonly fetch: typeof fetch | undefined;
+
+  /** Asks the user where to save; resolves with the file's handle. */
+  readonly pickSaveFile: (init: { suggestedName: string }) => Promise<FileSystemFileHandle>;
+  readonly update: (options: {
+    record: DownloadRecord;
+    changes: Partial<StoredItem>;
+  }) => void;
+}
+
+async function sizeOf(location: string) {
+  try {
+    return (await stat(location)).size;
+  } catch {
+    return 0;
+  }
+}
+
+function headersOf(pairs: ReadonlyArray<{
+  name: string;
+  value: string;
+}> | undefined) {
+  const headers = new Headers();
+  for (const { name, value } of pairs ?? []) {
+    headers.append(name, value);
+  }
+
+  return headers;
+}
+
+async function resolveTarget({ record, download, context }: {
+  record: DownloadRecord;
+  download: DownloadResponse;
+  context: TransferContext;
+}) {
+  const { options } = record;
+  const name = suggestedName({
+    filename: options.filename,
+    disposition: download.response.headers.get("content-disposition"),
+    address: download.url
+  });
+  const isAsked = options.saveAs === true || options.conflictAction === FilenameConflictAction.PROMPT;
+  if (isAsked) {
+    const handle = await context.pickSaveFile({ suggestedName: path.basename(name) });
+    record.finalPath = handle.path;
+    record.partialPath = handle.path;
+    return;
+  }
+
+  const wanted = path.join(context.directory, name);
+  const isOverwriting = options.conflictAction === FilenameConflictAction.OVERWRITE;
+  const finalPath = isOverwriting ? wanted : uniquePath(wanted);
+  await mkdir(path.dirname(finalPath), { recursive: true });
+  record.finalPath = finalPath;
+  record.partialPath = `${finalPath}.part`;
+}
+
+/**
+ * Runs one attempt of a download: asks for the file (the rest of it when
+ * `isResuming`), picks where it goes the first time, streams it to disk and,
+ * when it is whole, moves it to its name.
+ *
+ * @param options - The record, whether it continues an earlier attempt, and the context.
+ * @throws {Error} Whatever stopped the attempt, for the caller to read as paused, cancelled or interrupted.
+ */
+export async function transfer({ record, isResuming, context }: {
+  record: DownloadRecord;
+  isResuming: boolean;
+  context: TransferContext;
+}) {
+  const { options } = record;
+  const { partialPath: earlierPath } = record;
+  const isContinuing = isResuming && earlierPath !== undefined;
+  const offset = isContinuing ? await sizeOf(earlierPath) : 0;
+  const download = await requestDownload({
+    url: options.url,
+    offset,
+    headers: headersOf(options.headers),
+    signal: record.controller.signal,
+    ...options.method !== undefined && {
+      method: options.method
+    },
+    ...options.body !== undefined && {
+      body: options.body
+    },
+    ...context.fetch && {
+      fetch: context.fetch
+    }
+  });
+  const isUnplaced = record.partialPath === undefined;
+  if (isUnplaced) {
+    await resolveTarget({
+      record,
+      download,
+      context
+    });
+  }
+
+  const { partialPath, finalPath } = record;
+  const isPlaced = partialPath !== undefined && finalPath !== undefined;
+  if (!isPlaced) {
+    throw new Error("The download has no place to go");
+  }
+
+  context.update({
+    record,
+    changes: {
+      filename: finalPath,
+      finalUrl: download.url,
+      mime: download.response.headers.get("content-type")?.split(";")[0]?.trim() ?? ""
+    }
+  });
+  const bytes = await streamToFile({
+    download,
+    handle: new FileSystemFileHandle(partialPath),
+    onprogress(progress) {
+      context.update({
+        record,
+        changes: {
+          bytesReceived: progress.loaded,
+          totalBytes: progress.total ?? -1
+        }
+      });
+      record.report.update(progress);
+    }
+  });
+  const isMoved = partialPath !== finalPath;
+  if (isMoved) {
+    await rename(partialPath, finalPath);
+  }
+
+  record.report.end(TaskbarProgressState.NONE);
+  context.update({
+    record,
+    changes: {
+      state: DownloadState.COMPLETE,
+      endTime: new Date().toISOString(),
+      bytesReceived: bytes,
+      totalBytes: bytes,
+      fileSize: bytes,
+      exists: true,
+      canResume: false,
+      paused: false
+    }
+  });
+}