@fieldia/core 0.20.0 → 0.22.0

package/src/lib/record/upload-to.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-to.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/record/upload-to.ts"],"names":[],"mappings":"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"}

package/src/lib/record/uploads.d.mts

@@ -0,0 +1,152 @@
+import type { Field, Fields, LineField } from '../format/field.mjs';
+import { type DataSource, type UploadFile } from './data-source.mjs';
+import { type Messages } from './messages.mjs';
+import type { FileValue, RecordId, Value, Values } from './values.mjs';
+/**
+ * Files stored as they are picked. Where the data source has `upload`, a
+ * file or picture field hands each file to the form, which sends it to the
+ * app's store at once — three at a time, the rest waiting their turn, each
+ * made ready first when the field asks (a photo made smaller), one at a time
+ * — and puts the stored file's link in the field, in the order the files were
+ * picked. The form's state shows each on its way; Cancel stops one, Retry
+ * sends a failed one again. A save waits for those still going, and stops
+ * under its field for one that did not get there. A file still held as its
+ * bytes — a signature drawn, a value the app set — is stored by the save.
+ */
+/** A file on its way to the store, as the form's state shows it. */
+export interface FileUpload {
+    readonly id: string;
+    /** The file or picture field it is for: on a table's line, the line's own field. */
+    readonly field: string;
+    /** For a field on a line of a table: the table's field and the line's key. */
+    readonly line?: {
+        readonly field: string;
+        readonly key: string;
+    };
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    /**
+     * `waiting` its turn; `preparing`, made ready first (a photo made smaller);
+     * `uploading`, `sent` of `total` bytes on their way; `failed`, not stored —
+     * Retry may mend it; `refused`, the store will not keep it, `error` says why.
+     */
+    readonly status: 'waiting' | 'preparing' | 'uploading' | 'failed' | 'refused';
+    readonly sent: number;
+    /** The bytes in all, once the store has told them: null, and its bar moves with no number. */
+    readonly total: number | null;
+    /** Why it failed, or why the store refused it. */
+    readonly error?: string;
+}
+/** How files are taken, besides the field they are for. */
+export interface UploadHow {
+    /** For a field on a line of a table: the table's field and the line's key. */
+    line?: {
+        field: string;
+        key: string;
+    };
+    /** Each file made ready before it goes, one at a time: a photo made smaller. A file it cannot make ready goes as it is. */
+    prepare?: (file: UploadFile) => Promise<UploadFile>;
+}
+/** How many files go to the store at once; the rest wait their turn. */
+export declare const UPLOADS_AT_ONCE = 3;
+/** Whether an upload is still going: waiting, being made ready, or on its way. */
+export declare const uploadGoing: (upload: FileUpload) => boolean;
+/** What the form gives the uploads: where files go, where their links are put, and how the state is told. */
+export interface UploadsHost {
+    source(): DataSource | undefined;
+    /** The page's model, or a page of responses' id; for a saved form placed in a record, the record's. */
+    model(): string;
+    recordId(): RecordId | null;
+    /**
+     * Where the form's fields sit in the record its files are for, before each
+     * field's name: a saved form placed in a record keeps its answers under the
+     * part's name, so its field `doc` is `consent.doc` there. Empty otherwise.
+     */
+    under?: string;
+    /** A line's id, once it is saved. */
+    lineId(field: string, key: string): RecordId | undefined;
+    /** A field's or a line field's definition, or null when it holds no files. */
+    fileField(field: string, line?: {
+        field: string;
+        key: string;
+    }): Field | LineField | null;
+    /** The field's value now. */
+    read(field: string, line?: {
+        field: string;
+        key: string;
+    }): Value | undefined;
+    /** Write the field: a person's pick, or (`quiet`) a save putting a link in place of the bytes. */
+    write(field: string, line: {
+        field: string;
+        key: string;
+    } | undefined, value: Value, quiet: boolean): void;
+    changed(uploads: readonly FileUpload[]): void;
+    track<T>(promise: Promise<T>): Promise<T>;
+}
+interface Entry {
+    id: string;
+    /** Its place in the order files were picked. */
+    seq: number;
+    field: string;
+    line?: {
+        field: string;
+        key: string;
+    };
+    file: UploadFile;
+    prepare?: (file: UploadFile) => Promise<UploadFile>;
+    /** Made ready, or needing nothing done. */
+    ready: boolean;
+    /** The file held as its bytes that this one is stored for: a save puts the link in its place. */
+    replaces?: FileValue;
+    status: FileUpload['status'];
+    sent: number;
+    total: number | null;
+    error?: string;
+    stop?: () => void;
+    /** Ends its run: stored, failed, refused or cancelled. */
+    end?: () => void;
+}
+/** A file held as its bytes, as the store takes a file: its name, size, kind and bytes. */
+export declare function fileFromBytes(file: FileValue): UploadFile;
+/**
+ * The values as a draft keeps them: a file held as its bytes is left out —
+ * a field holding one is not kept at all, and a line's loses that file —
+ * so a draft stays small enough for the browser's store, and restoring it
+ * leaves those fields as the record holds them.
+ */
+export declare function withoutFileBytes(fields: Fields, values: Readonly<Values>): Values;
+/** Each file still held as its bytes in the fields that changed — on the record, or on a changed table's lines — for a save to store. */
+export declare function fileBytesIn(fields: Fields, values: Readonly<Values>, changed: readonly string[]): {
+    field: string;
+    line?: {
+        field: string;
+        key: string;
+    };
+    file: FileValue;
+}[];
+/** The uploads of one form. */
+export declare function createUploads(host: UploadsHost): {
+    /** Send files picked for a field: its ids. */
+    start(field: string, files: readonly UploadFile[], how?: {
+        line?: Entry["line"];
+        prepare?: Entry["prepare"];
+    }): string[];
+    cancel(id: string): void;
+    retry(id: string): void;
+    /** Stop every upload: the changes they were for are gone. */
+    clear(): void;
+    /** Whether any file is still going. */
+    going: () => boolean;
+    settled: () => Promise<void>;
+    /** Store each file still held as its bytes in the fields given, and wait for them all. */
+    storeBytes(found: {
+        field: string;
+        line?: Entry["line"];
+        file: FileValue;
+    }[]): Promise<void>;
+    /** What stops a save, under each field: a file that failed, or that the store refused. */
+    problems(messages: Messages): Record<string, string>;
+};
+export type Uploads = ReturnType<typeof createUploads>;
+export {};

package/src/lib/record/uploads.d.ts

@@ -0,0 +1,152 @@
+import type { Field, Fields, LineField } from '../format/field';
+import { type DataSource, type UploadFile } from './data-source';
+import { type Messages } from './messages';
+import type { FileValue, RecordId, Value, Values } from './values';
+/**
+ * Files stored as they are picked. Where the data source has `upload`, a
+ * file or picture field hands each file to the form, which sends it to the
+ * app's store at once — three at a time, the rest waiting their turn, each
+ * made ready first when the field asks (a photo made smaller), one at a time
+ * — and puts the stored file's link in the field, in the order the files were
+ * picked. The form's state shows each on its way; Cancel stops one, Retry
+ * sends a failed one again. A save waits for those still going, and stops
+ * under its field for one that did not get there. A file still held as its
+ * bytes — a signature drawn, a value the app set — is stored by the save.
+ */
+/** A file on its way to the store, as the form's state shows it. */
+export interface FileUpload {
+    readonly id: string;
+    /** The file or picture field it is for: on a table's line, the line's own field. */
+    readonly field: string;
+    /** For a field on a line of a table: the table's field and the line's key. */
+    readonly line?: {
+        readonly field: string;
+        readonly key: string;
+    };
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    /**
+     * `waiting` its turn; `preparing`, made ready first (a photo made smaller);
+     * `uploading`, `sent` of `total` bytes on their way; `failed`, not stored —
+     * Retry may mend it; `refused`, the store will not keep it, `error` says why.
+     */
+    readonly status: 'waiting' | 'preparing' | 'uploading' | 'failed' | 'refused';
+    readonly sent: number;
+    /** The bytes in all, once the store has told them: null, and its bar moves with no number. */
+    readonly total: number | null;
+    /** Why it failed, or why the store refused it. */
+    readonly error?: string;
+}
+/** How files are taken, besides the field they are for. */
+export interface UploadHow {
+    /** For a field on a line of a table: the table's field and the line's key. */
+    line?: {
+        field: string;
+        key: string;
+    };
+    /** Each file made ready before it goes, one at a time: a photo made smaller. A file it cannot make ready goes as it is. */
+    prepare?: (file: UploadFile) => Promise<UploadFile>;
+}
+/** How many files go to the store at once; the rest wait their turn. */
+export declare const UPLOADS_AT_ONCE = 3;
+/** Whether an upload is still going: waiting, being made ready, or on its way. */
+export declare const uploadGoing: (upload: FileUpload) => boolean;
+/** What the form gives the uploads: where files go, where their links are put, and how the state is told. */
+export interface UploadsHost {
+    source(): DataSource | undefined;
+    /** The page's model, or a page of responses' id; for a saved form placed in a record, the record's. */
+    model(): string;
+    recordId(): RecordId | null;
+    /**
+     * Where the form's fields sit in the record its files are for, before each
+     * field's name: a saved form placed in a record keeps its answers under the
+     * part's name, so its field `doc` is `consent.doc` there. Empty otherwise.
+     */
+    under?: string;
+    /** A line's id, once it is saved. */
+    lineId(field: string, key: string): RecordId | undefined;
+    /** A field's or a line field's definition, or null when it holds no files. */
+    fileField(field: string, line?: {
+        field: string;
+        key: string;
+    }): Field | LineField | null;
+    /** The field's value now. */
+    read(field: string, line?: {
+        field: string;
+        key: string;
+    }): Value | undefined;
+    /** Write the field: a person's pick, or (`quiet`) a save putting a link in place of the bytes. */
+    write(field: string, line: {
+        field: string;
+        key: string;
+    } | undefined, value: Value, quiet: boolean): void;
+    changed(uploads: readonly FileUpload[]): void;
+    track<T>(promise: Promise<T>): Promise<T>;
+}
+interface Entry {
+    id: string;
+    /** Its place in the order files were picked. */
+    seq: number;
+    field: string;
+    line?: {
+        field: string;
+        key: string;
+    };
+    file: UploadFile;
+    prepare?: (file: UploadFile) => Promise<UploadFile>;
+    /** Made ready, or needing nothing done. */
+    ready: boolean;
+    /** The file held as its bytes that this one is stored for: a save puts the link in its place. */
+    replaces?: FileValue;
+    status: FileUpload['status'];
+    sent: number;
+    total: number | null;
+    error?: string;
+    stop?: () => void;
+    /** Ends its run: stored, failed, refused or cancelled. */
+    end?: () => void;
+}
+/** A file held as its bytes, as the store takes a file: its name, size, kind and bytes. */
+export declare function fileFromBytes(file: FileValue): UploadFile;
+/**
+ * The values as a draft keeps them: a file held as its bytes is left out —
+ * a field holding one is not kept at all, and a line's loses that file —
+ * so a draft stays small enough for the browser's store, and restoring it
+ * leaves those fields as the record holds them.
+ */
+export declare function withoutFileBytes(fields: Fields, values: Readonly<Values>): Values;
+/** Each file still held as its bytes in the fields that changed — on the record, or on a changed table's lines — for a save to store. */
+export declare function fileBytesIn(fields: Fields, values: Readonly<Values>, changed: readonly string[]): {
+    field: string;
+    line?: {
+        field: string;
+        key: string;
+    };
+    file: FileValue;
+}[];
+/** The uploads of one form. */
+export declare function createUploads(host: UploadsHost): {
+    /** Send files picked for a field: its ids. */
+    start(field: string, files: readonly UploadFile[], how?: {
+        line?: Entry["line"];
+        prepare?: Entry["prepare"];
+    }): string[];
+    cancel(id: string): void;
+    retry(id: string): void;
+    /** Stop every upload: the changes they were for are gone. */
+    clear(): void;
+    /** Whether any file is still going. */
+    going: () => boolean;
+    settled: () => Promise<void>;
+    /** Store each file still held as its bytes in the fields given, and wait for them all. */
+    storeBytes(found: {
+        field: string;
+        line?: Entry["line"];
+        file: FileValue;
+    }[]): Promise<void>;
+    /** What stops a save, under each field: a file that failed, or that the store refused. */
+    problems(messages: Messages): Record<string, string>;
+};
+export type Uploads = ReturnType<typeof createUploads>;
+export {};

package/src/lib/record/uploads.js

@@ -0,0 +1,345 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadGoing = exports.UPLOADS_AT_ONCE = void 0;
+exports.fileFromBytes = fileFromBytes;
+exports.withoutFileBytes = withoutFileBytes;
+exports.fileBytesIn = fileBytesIn;
+exports.createUploads = createUploads;
+const data_source_1 = require("./data-source");
+const messages_1 = require("./messages");
+/** How many files go to the store at once; the rest wait their turn. */
+exports.UPLOADS_AT_ONCE = 3;
+const going = (status) => status !== 'failed' && status !== 'refused';
+/** Whether an upload is still going: waiting, being made ready, or on its way. */
+const uploadGoing = (upload) => going(upload.status);
+exports.uploadGoing = uploadGoing;
+/** The host's `AbortController`: every browser's, and Node's. Core names no DOM types. */
+const stopper = () => new globalThis.AbortController();
+const sameFile = (a, b) => a.name === b.name && a.data === b.data && a.url === b.url;
+const isFile = (value) => !!value && typeof value === 'object' && typeof value.name === 'string' && typeof value.size === 'number';
+const filesIn = (value) => (Array.isArray(value) ? value.filter(isFile) : isFile(value) ? [value] : []);
+const holdsFiles = (def) => def?.type === 'binary' || def?.type === 'image';
+/** The bytes a base64 text holds. */
+function bytesOf(data) {
+    const text = globalThis.atob(data);
+    const bytes = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i++)
+        bytes[i] = text.charCodeAt(i);
+    return bytes;
+}
+/** A file held as its bytes, as the store takes a file: its name, size, kind and bytes. */
+function fileFromBytes(file) {
+    const bytes = bytesOf(file.data ?? '');
+    return { name: file.name, size: bytes.length, type: file.type, arrayBuffer: async () => bytes.slice().buffer };
+}
+/**
+ * The values as a draft keeps them: a file held as its bytes is left out —
+ * a field holding one is not kept at all, and a line's loses that file —
+ * so a draft stays small enough for the browser's store, and restoring it
+ * leaves those fields as the record holds them.
+ */
+function withoutFileBytes(fields, values) {
+    const kept = {};
+    for (const [name, value] of Object.entries(values)) {
+        const def = fields[name];
+        if (holdsFiles(def)) {
+            if (!filesIn(value).some((file) => file.data !== undefined))
+                kept[name] = value;
+        }
+        else if (def?.type === 'one2many' && Array.isArray(value)) {
+            const subs = Object.entries(def.fields).filter(([, sub]) => holdsFiles(sub)).map(([sub]) => sub);
+            kept[name] = !subs.length
+                ? value
+                : value.map((line) => {
+                    const own = { ...line.values };
+                    for (const sub of subs)
+                        if (filesIn(own[sub]).some((file) => file.data !== undefined))
+                            delete own[sub];
+                    return { ...line, values: own };
+                });
+        }
+        else
+            kept[name] = value;
+    }
+    return kept;
+}
+/** Each file still held as its bytes in the fields that changed — on the record, or on a changed table's lines — for a save to store. */
+function fileBytesIn(fields, values, changed) {
+    const found = [];
+    for (const name of changed) {
+        const def = fields[name];
+        if (holdsFiles(def))
+            for (const file of filesIn(values[name]))
+                if (file.data !== undefined)
+                    found.push({ field: name, file });
+        if (def?.type !== 'one2many')
+            continue;
+        for (const line of values[name] ?? []) {
+            for (const [sub, subDef] of Object.entries(def.fields)) {
+                if (holdsFiles(subDef))
+                    for (const file of filesIn(line.values[sub]))
+                        if (file.data !== undefined)
+                            found.push({ field: sub, line: { field: name, key: line.key }, file });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * A field's files with a stored one put in: in place of the bytes it was
+ * stored for (nothing, when those are gone), in place of a field's one file,
+ * or among several before the first that was picked after it.
+ */
+function placed(current, stored, how) {
+    if (how.replaces) {
+        const was = how.replaces;
+        if (Array.isArray(current)) {
+            const at = current.findIndex((file) => isFile(file) && sameFile(file, was));
+            return at < 0 ? undefined : current.map((file, i) => (i === at ? stored : file));
+        }
+        return isFile(current) && sameFile(current, was) ? stored : undefined;
+    }
+    if (!how.several)
+        return stored;
+    const files = filesIn(current);
+    const at = files.findIndex(how.pickedAfter);
+    const list = at < 0 ? [...files, stored] : [...files.slice(0, at), stored, ...files.slice(at)];
+    return list;
+}
+/** The uploads of one form. */
+function createUploads(host) {
+    let entries = [];
+    let made = 0;
+    let picked = 0;
+    /** Where each stored file came in the order picked, by its link: a later one goes after it. */
+    const order = new Map();
+    const waiters = new Set();
+    const shown = (entry) => ({
+        id: entry.id,
+        field: entry.field,
+        ...(entry.line ? { line: entry.line } : {}),
+        name: entry.file.name,
+        size: entry.file.size,
+        type: entry.file.type,
+        status: entry.status,
+        sent: entry.sent,
+        total: entry.total,
+        ...(entry.error !== undefined ? { error: entry.error } : {}),
+    });
+    function tell() {
+        host.changed(entries.map(shown));
+        if (!entries.some((entry) => going(entry.status)))
+            for (const done of [...waiters])
+                done();
+    }
+    function drop(entry) {
+        entries = entries.filter((other) => other !== entry);
+        entry.stop?.();
+        entry.end?.();
+    }
+    /** The next to be made ready, one at a time, and the next to go, three at a time. */
+    function pump() {
+        if (!entries.some((entry) => entry.status === 'preparing')) {
+            const next = entries.find((entry) => entry.status === 'waiting' && !entry.ready);
+            if (next)
+                void prepare(next);
+        }
+        for (let next = nextToSend(); next && entries.filter((entry) => entry.status === 'uploading').length < exports.UPLOADS_AT_ONCE; next = nextToSend())
+            void send(next);
+    }
+    const nextToSend = () => entries.find((entry) => entry.status === 'waiting' && entry.ready);
+    async function prepare(entry) {
+        entry.status = 'preparing';
+        tell();
+        const original = entry.file;
+        let refused = null;
+        try {
+            entry.file = await entry.prepare(original);
+        }
+        catch (error) {
+            // A file that cannot be made ready goes as it is, never lost — unless the field refuses it as it is (too large still).
+            const problem = (0, data_source_1.saveProblemOf)(error);
+            if (problem.kind === 'rule')
+                refused = problem.message;
+            entry.file = original;
+        }
+        entry.ready = true;
+        if (!entries.includes(entry))
+            return;
+        entry.status = refused === null ? 'waiting' : 'refused';
+        if (refused !== null) {
+            entry.error = refused;
+            entry.end?.();
+        }
+        tell();
+        pump();
+    }
+    async function send(entry) {
+        const source = host.source();
+        if (!source?.upload)
+            return;
+        const stop = stopper();
+        entry.status = 'uploading';
+        entry.sent = 0;
+        entry.total = null;
+        delete entry.error;
+        entry.stop = () => stop.abort();
+        tell();
+        const lineId = entry.line ? host.lineId(entry.line.field, entry.line.key) : undefined;
+        const under = host.under ?? '';
+        const request = {
+            model: host.model(),
+            // A line's field is named on its own, its table where it sits.
+            field: entry.line ? entry.field : `${under}${entry.field}`,
+            recordId: host.recordId(),
+            ...(entry.line ? { line: { ...entry.line, field: `${under}${entry.line.field}`, ...(lineId !== undefined ? { id: lineId } : {}) } } : {}),
+            signal: stop.signal,
+            onProgress: (sent, total) => {
+                if (entry.status !== 'uploading' || !entries.includes(entry))
+                    return;
+                // Told when the bar would move: a whole per cent, or the end.
+                const was = entry.total ? Math.floor((entry.sent * 100) / entry.total) : -1;
+                const now = total ? Math.floor((sent * 100) / total) : -1;
+                entry.sent = sent;
+                entry.total = total;
+                if (now !== was || sent === total)
+                    tell();
+            },
+        };
+        try {
+            const stored = await source.upload(entry.file, request);
+            if (!entries.includes(entry))
+                return;
+            entries = entries.filter((other) => other !== entry);
+            put(entry, stored);
+            entry.end?.();
+        }
+        catch (error) {
+            if (!entries.includes(entry) || stop.signal.aborted || error?.name === 'AbortError') {
+                if (entries.includes(entry))
+                    drop(entry);
+            }
+            else {
+                const problem = (0, data_source_1.saveProblemOf)(error);
+                entry.status = problem.kind === 'rule' ? 'refused' : 'failed';
+                entry.error = problem.message;
+                entry.end?.();
+            }
+        }
+        finally {
+            delete entry.stop;
+            tell();
+            pump();
+        }
+    }
+    /** The stored file in its field: exactly what the store gave — its other words kept, for bytes it stands in for. */
+    function put(entry, stored) {
+        const def = host.fileField(entry.field, entry.line);
+        const extra = {};
+        if (entry.replaces)
+            for (const [key, value] of Object.entries(entry.replaces))
+                if (!['data', 'url', 'name', 'size', 'type', 'fileId'].includes(key))
+                    extra[key] = value;
+        const file = { ...stored, ...extra };
+        order.set(file.url ?? '', entry.seq);
+        const value = placed(host.read(entry.field, entry.line), file, {
+            several: def?.multiple === true,
+            ...(entry.replaces ? { replaces: entry.replaces } : {}),
+            pickedAfter: (other) => (order.get(other.url ?? '') ?? -1) > entry.seq,
+        });
+        if (value !== undefined)
+            host.write(entry.field, entry.line, value, !!entry.replaces);
+    }
+    function begin(field, line, file, more) {
+        const entry = { id: `upload-${++made}`, seq: ++picked, field, ...(line ? { line } : {}), file, ...(more.prepare ? { prepare: more.prepare } : {}), ready: !more.prepare, ...(more.replaces ? { replaces: more.replaces } : {}), status: 'waiting', sent: 0, total: null };
+        entries = [...entries, entry];
+        void host.track(new Promise((resolve) => (entry.end = resolve)));
+        return entry;
+    }
+    /** Wait until no file is still going: each one stored, failed, refused or cancelled. */
+    const settled = () => new Promise((resolve) => {
+        if (!entries.some((entry) => going(entry.status)))
+            return resolve();
+        const done = () => (waiters.delete(done), resolve());
+        waiters.add(done);
+    });
+    return {
+        /** Send files picked for a field: its ids. */
+        start(field, files, how = {}) {
+            if (!host.source()?.upload)
+                throw new Error('The data source has no upload: files go inside the record');
+            const def = host.fileField(field, how.line);
+            if (!def)
+                throw new Error(how.line ? `The lines of "${how.line.field}" have no file field "${field}"` : `"${field}" is not a file or picture field`);
+            // A field of one file: the last one picked is the one it keeps; one still on its way is stopped.
+            if (def.multiple !== true) {
+                for (const entry of entries.filter((e) => e.field === field && e.line?.key === how.line?.key && e.line?.field === how.line?.field && !e.replaces))
+                    drop(entry);
+                files = files.slice(-1);
+            }
+            const started = files.map((file) => begin(field, how.line, file, { prepare: how.prepare }));
+            tell();
+            pump();
+            return started.map((entry) => entry.id);
+        },
+        cancel(id) {
+            const entry = entries.find((e) => e.id === id);
+            if (!entry)
+                return;
+            drop(entry);
+            tell();
+            pump();
+        },
+        retry(id) {
+            const entry = entries.find((e) => e.id === id);
+            if (!entry || entry.status !== 'failed')
+                return;
+            entry.status = 'waiting';
+            entry.sent = 0;
+            entry.total = null;
+            delete entry.error;
+            void host.track(new Promise((resolve) => (entry.end = resolve)));
+            tell();
+            pump();
+        },
+        /** Stop every upload: the changes they were for are gone. */
+        clear() {
+            if (!entries.length)
+                return;
+            for (const entry of [...entries])
+                drop(entry);
+            tell();
+        },
+        /** Whether any file is still going. */
+        going: () => entries.some((entry) => going(entry.status)),
+        settled,
+        /** Store each file still held as its bytes in the fields given, and wait for them all. */
+        async storeBytes(found) {
+            if (!found.length || !host.source()?.upload)
+                return;
+            for (const { field, line, file } of found)
+                begin(field, line, fileFromBytes(file), { replaces: file });
+            tell();
+            pump();
+            await settled();
+        },
+        /** What stops a save, under each field: a file that failed, or that the store refused. */
+        problems(messages) {
+            const out = {};
+            const by = new Map();
+            for (const entry of entries.filter((e) => !going(e.status))) {
+                const key = entry.line ? `${entry.line.field}.${entry.line.key}.${entry.field}` : entry.field;
+                by.set(key, [...(by.get(key) ?? []), entry]);
+            }
+            for (const [key, list] of by) {
+                const refused = list.filter((entry) => entry.status === 'refused');
+                out[key] =
+                    list.length > 1 ? (0, messages_1.fill)(messages.notUploadedMany, { n: list.length })
+                        : refused.length ? (0, messages_1.fill)(messages.fileRefused, { name: list[0].file.name, reason: list[0].error ?? '' })
+                            : (0, messages_1.fill)(messages.notUploaded, { name: list[0].file.name });
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=uploads.js.map