@filefreak.io/sdk 0.1.0 → 0.2.0

package/dist/links.d.ts

@@ -0,0 +1,72 @@
+import { type Sink } from "./ranges.js";
+/** A file a link holds, as get() hands it to the function that makes its sink. */
+export interface LinkedFile {
+    id: string;
+    /**
+     * Its name, as whoever shared it wrote it. A link can name any site, and
+     * that site can say anything, so never use it as a path unchecked:
+     * safeName and toFolder, in "@filefreak.io/sdk/node", check it.
+     */
+    name: string;
+    /** The folders it is in, from the shared folder, by its name, down. Empty for a link to one file. As unchecked as `name`. */
+    folders: string[];
+    sizeBytes: number;
+    contentType: string | null;
+    /** Under Shard Protection: put back together from its map, each part checked as it arrives. */
+    protected: boolean;
+}
+/** Where get() puts what a link holds: one Sink, for a link to one file, or a function that makes one for each file. */
+export type Into = Sink | ((file: LinkedFile) => Sink | Promise<Sink>);
+export interface GetOptions {
+    /** The link's password, for a link that has one. */
+    password?: string;
+    /** Stops the saving, and aborts the sink of the file being saved. */
+    signal?: AbortSignal;
+    /** Called as bytes are written, with how many have been and how many there are in all. */
+    onProgress?: (writtenBytes: number, totalBytes: number) => void;
+    /** Another fetch, for a runtime without one or for tests. */
+    fetch?: typeof fetch;
+}
+export interface Got {
+    /** What the link is to. */
+    kind: "file" | "folder";
+    /** Its name, as its sharer wrote it. */
+    name: string;
+    /** Every file saved, in the order they were saved. */
+    files: LinkedFile[];
+    /** Their bytes, together. */
+    sizeBytes: number;
+}
+/** What a link is to, and the site to ask about it. */
+export type Link = {
+    origin: string;
+} & ({
+    kind: "share";
+    token: string;
+} | {
+    kind: "public";
+    id: string;
+    username: string | null;
+});
+export declare const NOT_A_LINK = "That is not a FileFreak share link or public file address.";
+/**
+ * The link a web address is: `/share/<token>`, `/public/<username>/<id>`,
+ * or a public file's direct address, `/api/public/files/<id>/raw`. On https,
+ * or on http for the local stack only.
+ */
+export declare function linkOf(url: string | URL): Link;
+/**
+ * Save what a share link or a public page holds, with no key: one file into
+ * `into`, a Sink, or a folder and everything in it, each file into the Sink
+ * that `into`, a function, makes for it. Resolves once every file has been
+ * saved and its sink closed.
+ *
+ * Takes `https://<host>/share/<token>`, `https://<host>/public/<username>/<id>`
+ * and a public file's direct address. A protected file is put back together
+ * from its map and checked as it arrives. A failure is a FileFreakError, with
+ * the site's code and sentence or one of get's own: not_a_link, not_a_file
+ * (a folder's link given one Sink), password_required, not_enough_downloads,
+ * too_deep, fragment_damaged or fragment_unavailable. The file being saved
+ * when it stops has its sink aborted; files saved before it stay saved.
+ */
+export declare function get(url: string | URL, into: Into, options?: GetOptions): Promise<Got>;

package/dist/links.js

@@ -0,0 +1,355 @@
+// Saving what a share link or a public page holds, with no key: one file, or
+// a folder and everything in it (docs/reference/shard-links.md). For a
+// program that has been handed a link, as a person is, and has no account of
+// its own to use.
+//
+// It reads the link as the link's own page does, through the website's public
+// answers under /api/public at the link's own origin, which only ever grow
+// (api/src/routes/public.ts). It never sends a key, a token or a cookie: a
+// link can name any site, and that site is told nothing about whoever follows
+// it. For the same reason every answer is checked for the fields this reads
+// before anything is done with it. A plain file is fetched from its address in
+// ranges (ranges.ts), and a protected one is put back together from its map,
+// each part checked as it arrives (reader.ts).
+//
+// Each file saved counts as the link's page counts it: one of the link's
+// downloads, when it has a limit, and its size toward its owner's month. No
+// API call is counted, since no key is used.
+import { fetchRanges } from "./ranges.js";
+import { asItIsKept, readProtected } from "./reader.js";
+import { backoff, FileFreakError, sleep } from "./transport.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** As the API's route takes a token (api/src/routes/public.ts). */
+const TOKEN = /^[A-Za-z0-9_-]{20,80}$/;
+/** As the API's usernameSchema allows one, in either case: the website reads them without case. */
+const USERNAME = /^[A-Za-z0-9_]{3,30}$/;
+/** The local stack's two names, the only ones reached without https. */
+const LOCAL = new Set(["localhost", "127.0.0.1"]);
+/** Items asked for at once from a folder's listing: the most the API gives. */
+const PAGE = 200;
+/** How deep FileFreak lets folders go (api/src/services/removal.ts, MAX_DEPTH). A listing deeper than this is not FileFreak's. */
+const MAX_DEPTH = 32;
+const RETRIES = 4;
+/** The longest wait between tries, whatever Retry-After says. */
+const MOST_WAIT_MS = 60_000;
+/** A sleeping database takes about a minute to start. Five minutes of asking is plenty. */
+const WAKING_TRIES = 60;
+export const NOT_A_LINK = "That is not a FileFreak share link or public file address.";
+/**
+ * The link a web address is: `/share/<token>`, `/public/<username>/<id>`,
+ * or a public file's direct address, `/api/public/files/<id>/raw`. On https,
+ * or on http for the local stack only.
+ */
+export function linkOf(url) {
+    const notALink = (message = NOT_A_LINK) => new FileFreakError(0, "not_a_link", message);
+    let u;
+    try {
+        u = new URL(String(url));
+    }
+    catch {
+        throw notALink();
+    }
+    const secure = u.protocol === "https:" || (u.protocol === "http:" && LOCAL.has(u.hostname));
+    if (!secure || u.username || u.password)
+        throw notALink();
+    const [first, second, third, fourth, fifth, ...more] = u.pathname.split("/").filter((p) => p !== "");
+    if (more.length > 0)
+        throw notALink();
+    if (first === "share" && second && TOKEN.test(second) && third === undefined)
+        return { origin: u.origin, kind: "share", token: second };
+    if (first === "public" && second && USERNAME.test(second) && third && UUID.test(third) && fourth === undefined) {
+        return { origin: u.origin, kind: "public", id: third.toLowerCase(), username: second };
+    }
+    if (first === "public" && second && third === undefined)
+        throw notALink("That is somebody's public profile. Give the address of one of its files or folders.");
+    if (first === "api" && second === "public" && third === "files" && fourth && UUID.test(fourth) && fifth === "raw") {
+        return { origin: u.origin, kind: "public", id: fourth.toLowerCase(), username: null };
+    }
+    throw notALink();
+}
+function unreadable(origin) {
+    return new FileFreakError(0, "unreadable", `${origin} answered with something FileFreak would not: it may not be FileFreak, or not a version this SDK knows.`);
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isCount = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+/** Storage's addresses are https, or http on the local stack. Anything else a site sends, data: or file: among them, is not fetched. */
+const isWebAddress = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+/** The answers come from whatever site the link names, so each is checked before it is used. */
+class Reader {
+    origin;
+    constructor(origin) {
+        this.origin = origin;
+    }
+    fail() {
+        throw unreadable(this.origin);
+    }
+    item(v) {
+        if (!isObject(v) || typeof v.id !== "string" || !UUID.test(v.id) || (v.kind !== "file" && v.kind !== "folder") || typeof v.name !== "string")
+            this.fail();
+        if (v.kind === "file" && !isCount(v.sizeBytes))
+            this.fail();
+        const contentType = typeof v.contentType === "string" ? v.contentType : null;
+        return { id: v.id, kind: v.kind, name: v.name, sizeBytes: v.kind === "file" ? v.sizeBytes : 0, contentType, protected: v.protected === true };
+    }
+    listing(v) {
+        if (!isObject(v) || !Array.isArray(v.items) || !(v.nextOffset === null || isCount(v.nextOffset)))
+            this.fail();
+        return { items: v.items.map((i) => this.item(i)), nextOffset: v.nextOffset };
+    }
+    address(v) {
+        if (!isObject(v) || !isWebAddress(v.url))
+            this.fail();
+        return v.url;
+    }
+    map(v) {
+        if (!isObject(v) || typeof v.contentId !== "string" || typeof v.key !== "string" || typeof v.expiresAt !== "string" || typeof v.grant !== "string")
+            this.fail();
+        if (!isCount(v.sizeBytes) || !isCount(v.fragmentBytes) || !isCount(v.count) || !Array.isArray(v.fragments))
+            this.fail();
+        const fragments = v.fragments.map((f) => (isObject(f) && isCount(f.place) && isWebAddress(f.url) ? { place: f.place, url: f.url } : this.fail()));
+        return { contentId: v.contentId, sizeBytes: v.sizeBytes, fragmentBytes: v.fragmentBytes, count: v.count, key: v.key, fragments, expiresAt: v.expiresAt, grant: v.grant };
+    }
+}
+/** The link's own site, asked with nothing that says who is asking. */
+class Site {
+    origin;
+    fetcher;
+    signal;
+    read;
+    constructor(origin, fetcher, signal) {
+        this.origin = origin;
+        this.fetcher = fetcher;
+        this.signal = signal;
+        this.read = new Reader(origin);
+    }
+    /**
+     * One of the public answers. As the client's transport asks (transport.ts),
+     * but a request is sent again only when it is a read: a password sent twice
+     * is two tries against the link.
+     */
+    async ask(path, grants = {}, body, signal = this.signal) {
+        const method = body === undefined ? "GET" : "POST";
+        const headers = { Accept: "application/json" };
+        if (grants.share)
+            headers["X-Share-Grant"] = grants.share;
+        if (grants.read)
+            headers["X-Read-Grant"] = grants.read;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let waking = 0;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetcher(`${this.origin}${path}`, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    credentials: "omit",
+                    signal,
+                });
+            }
+            catch (e) {
+                if (signal?.aborted)
+                    throw signal.reason;
+                if (method !== "GET" || attempt >= RETRIES)
+                    throw new FileFreakError(0, "network_error", `${this.origin} could not be reached: ${e instanceof Error ? e.message : String(e)}`);
+                await sleep(backoff(attempt), signal);
+                continue;
+            }
+            const text = await res.text();
+            let parsed = null;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = null;
+            }
+            if (res.ok) {
+                if (!isObject(parsed))
+                    throw unreadable(this.origin);
+                return parsed;
+            }
+            const error = isObject(parsed) ? parsed : null;
+            const code = typeof error?.error === "string" ? error.error : `http_${res.status}`;
+            const message = typeof error?.message === "string" ? error.message : `${this.origin} answered ${res.status}.`;
+            // Not Number(header) alone: a missing header is null, and Number(null) is 0.
+            const header = res.headers.get("retry-after");
+            const after = header === null ? NaN : Number(header);
+            const retryAfter = Number.isFinite(after) && after >= 0 ? after : null;
+            const refusal = new FileFreakError(res.status, code, message, error, retryAfter);
+            if (res.status === 503 && code === "waking_up" && waking < WAKING_TRIES) {
+                waking++;
+                attempt--;
+                await sleep(Math.min(MOST_WAIT_MS, (retryAfter ?? 5) * 1000), signal);
+                continue;
+            }
+            const passing = method === "GET" && (res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504);
+            if (!passing || attempt >= RETRIES)
+                throw refusal;
+            await sleep(retryAfter !== null ? Math.min(MOST_WAIT_MS, retryAfter * 1000) : backoff(attempt), signal);
+        }
+    }
+}
+async function openShare(site, token, password) {
+    const base = `/api/public/shares/${token}`;
+    const describe = async (share) => {
+        const v = await site.ask(base, { share });
+        if (!isObject(v) || typeof v.locked !== "boolean" || !(v.downloadsLeft === null || isCount(v.downloadsLeft)))
+            throw unreadable(site.origin);
+        return { locked: v.locked, downloadsLeft: v.downloadsLeft, item: v.locked ? null : site.read.item(v.item) };
+    };
+    let share = null;
+    let view = await describe(null);
+    if (view.locked) {
+        if (!password)
+            throw new FileFreakError(401, "password_required", "This link needs a password. Give it as the password option.");
+        const unlocked = await site.ask(`${base}/unlock`, {}, { password });
+        if (!isObject(unlocked) || typeof unlocked.grant !== "string")
+            throw unreadable(site.origin);
+        share = unlocked.grant;
+        view = await describe(share);
+        if (view.locked)
+            throw unreadable(site.origin);
+    }
+    return {
+        root: view.item,
+        downloadsLeft: view.downloadsLeft,
+        list: async (folder, offset) => site.read.listing(await site.ask(`${base}/items?parent=${folder}&offset=${offset}&limit=${PAGE}`, { share })),
+        address: async (id) => site.read.address(await site.ask(`${base}/files/${id}/url`, { share })),
+        page: async (id, from, read, signal) => site.read.map(await site.ask(`${base}/files/${id}/shards?from=${from}`, { share, read }, undefined, signal)),
+    };
+}
+async function openPublic(site, id, username) {
+    const v = await site.ask(`/api/public/files/${id}`);
+    if (!isObject(v) || !isObject(v.owner) || typeof v.owner.username !== "string")
+        throw unreadable(site.origin);
+    // As the website's page: under another person's name, it is not there.
+    if (username !== null && v.owner.username.toLowerCase() !== username.toLowerCase()) {
+        throw new FileFreakError(404, "not_found", "That file is not public, or does not exist.");
+    }
+    return {
+        root: site.read.item(v.item),
+        downloadsLeft: null,
+        list: async (folder, offset) => site.read.listing(await site.ask(`/api/public/files/${folder}/items?offset=${offset}&limit=${PAGE}`)),
+        address: async (file) => site.read.address(await site.ask(`/api/public/files/${file}/url`)),
+        page: async (file, from, read, signal) => site.read.map(await site.ask(`/api/public/files/${file}/shards?from=${from}`, { read }, undefined, signal)),
+    };
+}
+/** Every file in a shared folder, with the folders it is in, read folder by folder. */
+async function walk(opened) {
+    const found = [];
+    const seen = new Set([opened.root.id]);
+    const visit = async (folder, folders, depth) => {
+        if (depth > MAX_DEPTH) {
+            throw new FileFreakError(0, "too_deep", `This folder has folders more than ${MAX_DEPTH} deep, which FileFreak's never do. Nothing was saved.`);
+        }
+        for (let offset = 0; offset !== null;) {
+            const page = await opened.list(folder.id, offset);
+            for (const item of page.items) {
+                // Listed twice, as when something was added between two pages: saved once.
+                if (seen.has(item.id))
+                    continue;
+                seen.add(item.id);
+                if (item.kind === "folder")
+                    await visit(item, [...folders, item.name], depth + 1);
+                else
+                    found.push({ item, folders });
+            }
+            // A next page that does not move on would be asked for for ever.
+            offset = page.nextOffset !== null && page.nextOffset > offset ? page.nextOffset : null;
+        }
+    };
+    await visit(opened.root, [opened.root.name], 0);
+    return found;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/**
+ * Save what a share link or a public page holds, with no key: one file into
+ * `into`, a Sink, or a folder and everything in it, each file into the Sink
+ * that `into`, a function, makes for it. Resolves once every file has been
+ * saved and its sink closed.
+ *
+ * Takes `https://<host>/share/<token>`, `https://<host>/public/<username>/<id>`
+ * and a public file's direct address. A protected file is put back together
+ * from its map and checked as it arrives. A failure is a FileFreakError, with
+ * the site's code and sentence or one of get's own: not_a_link, not_a_file
+ * (a folder's link given one Sink), password_required, not_enough_downloads,
+ * too_deep, fragment_damaged or fragment_unavailable. The file being saved
+ * when it stops has its sink aborted; files saved before it stay saved.
+ */
+export async function get(url, into, options = {}) {
+    const make = typeof into === "function" ? into : null;
+    const given = typeof into === "function" ? null : into;
+    const signal = options.signal;
+    try {
+        const link = linkOf(url);
+        const fetcher = options.fetch ?? fetch.bind(globalThis);
+        const site = new Site(link.origin, fetcher, signal);
+        const opened = link.kind === "share" ? await openShare(site, link.token, options.password) : await openPublic(site, link.id, link.username);
+        const { root } = opened;
+        if (root.kind === "folder" && given) {
+            throw new FileFreakError(400, "not_a_file", 'That link is to a folder. Give get() a function that makes a sink for each file, as toFolder in "@filefreak.io/sdk/node" does.');
+        }
+        const found = root.kind === "file" ? [{ item: root, folders: [] }] : await walk(opened);
+        // Each file saved is one of the link's downloads, as on its page. Saving
+        // part of a folder and using the link up doing it helps nobody.
+        const counted = found.filter((f) => f.item.sizeBytes > 0).length;
+        const left = opened.downloadsLeft;
+        if (left !== null && counted > left) {
+            if (left === 0)
+                throw new FileFreakError(410, "link_used_up", "This link has been used as many times as it allows.");
+            throw new FileFreakError(410, "not_enough_downloads", `This link allows ${plural(left, "more download", "more downloads")}, and saving everything in it takes ${counted}: each file is one. Nothing was saved.`);
+        }
+        const total = found.reduce((n, f) => n + f.item.sizeBytes, 0);
+        const saved = [];
+        let before = 0;
+        for (const { item, folders } of found) {
+            const file = { id: item.id, name: item.name, folders, sizeBytes: item.sizeBytes, contentType: item.contentType, protected: item.protected };
+            const sink = given ?? (await make(file));
+            try {
+                await saveOne(opened, item, sink, fetcher, signal, (written) => options.onProgress?.(before + written, total));
+                await sink.close?.();
+            }
+            catch (e) {
+                if (!given)
+                    await sink.abort?.(e).catch(() => undefined);
+                throw e;
+            }
+            before += item.sizeBytes;
+            saved.push(file);
+        }
+        return { kind: root.kind, name: root.name, files: saved, sizeBytes: total };
+    }
+    catch (e) {
+        await given?.abort?.(e).catch(() => undefined);
+        throw e;
+    }
+}
+/** One file of a link into its sink: from its address, or through its map. */
+async function saveOne(opened, item, sink, fetcher, signal, progress) {
+    // Nothing to fetch, and asking would count a download of nothing.
+    if (item.sizeBytes === 0)
+        return;
+    await asItIsKept(item.protected, async () => {
+        const url = await opened.address(item.id);
+        await fetchRanges({ url, sizeBytes: item.sizeBytes, sink, signal, progress, fetch: fetcher, sleep: (ms) => sleep(ms, signal) });
+    }, async () => {
+        // One reading: the first page counts it, and each page after carries
+        // the newest read grant on, held here in memory and nowhere else.
+        let read = null;
+        await readProtected({
+            pages: async (from, pageSignal) => {
+                const page = await opened.page(item.id, from, read, pageSignal);
+                read = page.grant;
+                return page;
+            },
+            sink,
+            signal,
+            progress,
+            fetch: fetcher,
+            sizeBytes: item.sizeBytes,
+        });
+    });
+}

package/dist/node.d.ts

@@ -1,3 +1,4 @@
+import type { LinkedFile } from "./links.js";
 import type { Sink } from "./ranges.js";
 /**
  * A file on disk, to upload: read a part at a time as it is sent, never held
@@ -14,3 +15,22 @@ export declare function fromPath(path: string, options?: {
  * where it was meant to be.
  */
 export declare function toPath(path: string): Promise<Sink>;
+/**
+ * A name from a link, as a name this computer can hold that cannot step out
+ * of the folder it is written in: the part after its last slash or
+ * backslash, with what cannot be in a name written as "_". An empty name,
+ * "." or ".." is `fallback`. The CLI's filefreak get keeps names by the same
+ * rule.
+ */
+export declare function safeName(name: string, fallback: string, windows?: boolean): string;
+/**
+ * Where get() saves a link's files: each in `dir`, in the folders the link
+ * has it in, made as they are needed. Every name is the sharer's, so each is
+ * made safe first (safeName), and names FileFreak keeps apart can then come
+ * out as one ("a\u0001" and "a\u0002" are both "a_"). Compared without
+ * case, since many disks do, folders that come out as one name are one
+ * folder, and a file that comes out as the name of another file or a folder
+ * is told apart as "name (2).ext", as filefreak get does. A file's ".part"
+ * is its place too while it is written. Nothing is written outside `dir`.
+ */
+export declare function toFolder(dir: string): (file: LinkedFile) => Promise<Sink>;

package/dist/node.js

@@ -1,12 +1,14 @@
-// Files on disk, for a program in Node: one to upload, and one to download
-// into. Apart from the main entry, which runs in browsers too.
+// Files on disk, for a program in Node: one to upload, one to download into,
+// and a folder to save a link's files in. Apart from the main entry, which
+// runs in browsers too.
 //
-//   import { fromPath, toPath } from "@filefreak.io/sdk/node";
+//   import { fromPath, toFolder, toPath } from "@filefreak.io/sdk/node";
 //   const item = await ff.upload(await fromPath("film.mp4"));
 //   await ff.download(item.id, await toPath("copy.mp4"));
+//   await get("https://filefreak.link/share/...", toFolder("downloads"));
 import { openAsBlob } from "node:fs";
-import { open, rename, rm } from "node:fs/promises";
-import { basename } from "node:path";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { basename, extname, join, resolve, sep } from "node:path";
 /**
  * A file on disk, to upload: read a part at a time as it is sent, never held
  * whole. Node refuses to read it if it changes on disk in the meantime, so a
@@ -23,7 +25,7 @@ export async function fromPath(path, options = {}) {
  * where it was meant to be.
  */
 export async function toPath(path) {
-    const partial = `${path}.part`;
+    const partial = partialOf(path);
     const handle = await open(partial, "w");
     let shut = false;
     const close = async () => {
@@ -49,3 +51,74 @@ export async function toPath(path) {
         },
     };
 }
+/** Where toPath writes a file until every byte is there. */
+const partialOf = (path) => `${path}.part`;
+/** Characters that are never kept in a name from a link: controls, and the ones that turn text around so ".exe" can read as ".pdf". */
+const UNSEEN = /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/** What Windows cannot hold in a name. */
+const NOT_ON_WINDOWS = /[<>:"|?*]/g;
+/** Names Windows keeps for devices, with or without an extension. */
+const DEVICE = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i;
+/**
+ * A name from a link, as a name this computer can hold that cannot step out
+ * of the folder it is written in: the part after its last slash or
+ * backslash, with what cannot be in a name written as "_". An empty name,
+ * "." or ".." is `fallback`. The CLI's filefreak get keeps names by the same
+ * rule.
+ */
+export function safeName(name, fallback, windows = process.platform === "win32") {
+    let out = (name.split(/[/\\]/).pop() ?? "").replace(UNSEEN, "_");
+    if (windows) {
+        out = out.replace(NOT_ON_WINDOWS, "_").replace(/[ .]+$/, "");
+        if (DEVICE.test(out))
+            out = `_${out}`;
+    }
+    return out === "" || out === "." || out === ".." ? fallback : out;
+}
+/**
+ * Where get() saves a link's files: each in `dir`, in the folders the link
+ * has it in, made as they are needed. Every name is the sharer's, so each is
+ * made safe first (safeName), and names FileFreak keeps apart can then come
+ * out as one ("a\u0001" and "a\u0002" are both "a_"). Compared without
+ * case, since many disks do, folders that come out as one name are one
+ * folder, and a file that comes out as the name of another file or a folder
+ * is told apart as "name (2).ext", as filefreak get does. A file's ".part"
+ * is its place too while it is written. Nothing is written outside `dir`.
+ */
+export function toFolder(dir) {
+    const root = resolve(dir);
+    // Each place given, in lower case, as a file's or a folder's.
+    const taken = new Map();
+    // Each of the link's folders, by its names from the top, and where it is here.
+    const made = new Map();
+    const given = (path, kind) => kind === "folder" ? taken.get(path.toLowerCase()) === "file" : taken.has(path.toLowerCase()) || taken.has(partialOf(path).toLowerCase());
+    const place = (under, name, kind) => {
+        const ext = kind === "file" ? extname(name) : "";
+        const stem = name.slice(0, name.length - ext.length);
+        let path = join(under, name);
+        for (let n = 2; given(path, kind); n++)
+            path = join(under, `${stem} (${n})${ext}`);
+        taken.set(path.toLowerCase(), kind);
+        if (kind === "file")
+            taken.set(partialOf(path).toLowerCase(), "file");
+        return path;
+    };
+    return async (file) => {
+        let folder = root;
+        for (let i = 0; i < file.folders.length; i++) {
+            const key = JSON.stringify(file.folders.slice(0, i + 1));
+            let here = made.get(key);
+            if (here === undefined) {
+                here = place(folder, safeName(file.folders[i], "folder"), "folder");
+                made.set(key, here);
+            }
+            folder = here;
+        }
+        const path = place(folder, safeName(file.name, "download"), "file");
+        // safeName already keeps every part inside; this is the rule said once more where it matters.
+        if (!path.startsWith(root + sep))
+            throw new Error(`${JSON.stringify(file.name)} would be saved outside ${root}.`);
+        await mkdir(folder, { recursive: true });
+        return await toPath(path);
+    };
+}

package/dist/reader.d.ts

@@ -0,0 +1,76 @@
+import type { Sink } from "./ranges.js";
+/** The most bytes of fragments being fetched, or fetched and not yet written, at once in this program: five of the largest. */
+export declare const MOST_IN_FLIGHT_BYTES: number;
+/** Fragments fetched at once from one storage host. */
+export declare const PER_HOST = 6;
+/** Said when a fragment arrives and fails its check. */
+export declare const NOT_WHAT_WAS_STORED = "Part of this file is not what was stored. Nothing was saved.";
+/** Said when a fragment cannot be had from storage. */
+export declare const NOT_FETCHED = "Part of this file could not be fetched from storage. Nothing was saved; try again later.";
+/** A page of a protected file's map, as the reader uses it: files.shards's answer, or a link's. */
+export interface MapPage {
+    contentId: string;
+    sizeBytes: number;
+    fragmentBytes: number;
+    count: number;
+    /** The file's key, in base64. */
+    key: string;
+    fragments: ReadonlyArray<{
+        place: number;
+        url: string;
+    }>;
+    /** When this page's addresses stop working. */
+    expiresAt: string;
+}
+/** Asks for the page of a map that begins at a place. A function, so that a map is read the same way whoever gives it. */
+export type Pages = (from: number, signal: AbortSignal) => Promise<MapPage>;
+/**
+ * A number of units, taken and given back, first come first served: a
+ * budget of bytes, or turns at a host. A taker who asks for more than there
+ * ever is waits for all of it, and goes alone.
+ */
+export declare class Gate {
+    private readonly most;
+    private free;
+    private readonly queue;
+    constructor(most: number);
+    /** Wait for `units`. Answers the way to give them back, which may be called more than once. */
+    take(units: number, signal: AbortSignal): Promise<() => void>;
+    private giver;
+    private next;
+}
+export interface ReadOptions {
+    pages: Pages;
+    sink: Sink;
+    /**
+     * The file's size as it was listed. A map of another size is of a file
+     * replaced since, and is not read: a sink made for the size listed, as
+     * bytes() makes one, could not hold it.
+     */
+    sizeBytes?: number;
+    signal?: AbortSignal | undefined;
+    /** How many bytes of the file have been written, after each fragment. */
+    progress?: ((writtenBytes: number) => void) | undefined;
+    fetch?: typeof fetch;
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    now?: () => number;
+    /** Bytes of fragments in flight: the program's, unless a test gives a read its own. */
+    budget?: Gate;
+    /** Fragments fetched at once from one storage host. */
+    perHost?: number;
+    quietMs?: number;
+}
+/**
+ * Read the protected file whose map `pages` gives into `sink`. Resolves once
+ * every fragment has been written; the caller closes the sink, or aborts it
+ * when this rejects, as with fetchRanges. Rejects only once every fragment
+ * still in flight has stopped, so nothing is written to the sink after.
+ */
+export declare function readProtected(options: ReadOptions): Promise<void>;
+/**
+ * Fetch a file the way it is kept: through its map when it is protected,
+ * from its address when not. One converted since it was listed is refused
+ * the way the listing chose (409 not_protected, or shard_protected) before
+ * anything is written, and is fetched the other way, once.
+ */
+export declare function asItIsKept(isProtected: boolean, plain: () => Promise<void>, mapped: () => Promise<void>): Promise<void>;