@fieldia/core 0.21.0 → 0.23.0

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

@@ -0,0 +1,114 @@
+import { saveRefused } from './data-source.mjs';
+/** The statuses that say the store will not keep this file, whatever is tried: its size, its kind, what it holds. */
+const REFUSALS = new Set([400, 409, 413, 415, 422]);
+const stopped = () => Object.assign(new Error('The upload was stopped'), { name: 'AbortError' });
+/** An upload to a plain endpoint, for a data source: `{ ...source, upload: uploadTo({ url: '/api/files' }) }`. */
+export function uploadTo(options) {
+    const method = options.method ?? 'POST';
+    return async (file, request) => {
+        if (request.signal?.aborted)
+            throw stopped();
+        const host = globalThis;
+        const given = typeof options.url === 'function' ? await options.url(file, request) : options.url;
+        const target = typeof given === 'string' ? { url: given } : given;
+        const own = typeof options.headers === 'function' ? await options.headers(file, request) : (options.headers ?? {});
+        const headers = { ...own, ...target.headers };
+        // A file the browser picked is a Blob already; one held as bytes is made one.
+        const blob = file instanceof host.Blob ? file : new host.Blob([await file.arrayBuffer()], { type: file.type });
+        let body = blob;
+        if (method === 'PUT') {
+            if (!Object.keys(headers).some((name) => name.toLowerCase() === 'content-type'))
+                headers['Content-Type'] = file.type || 'application/octet-stream';
+        }
+        else {
+            const form = new host.FormData();
+            form.append(options.field ?? 'file', blob, file.name);
+            body = form;
+        }
+        const answer = await (host.XMLHttpRequest ? viaXhr : viaFetch)(host, { method, url: target.url, headers, body, file, request, withCredentials: options.withCredentials === true });
+        if (answer.status < 200 || answer.status >= 300) {
+            const said = wordsOf(answer);
+            if (REFUSALS.has(answer.status))
+                throw saveRefused({ kind: 'rule', message: said || `The store did not take ${file.name} (${answer.status})` });
+            throw new Error(said ? `${said} (${answer.status})` : `The store answered ${answer.status}`);
+        }
+        const linked = options.link ? await options.link(answer, file) : linkOf(answer, method, host);
+        if (!linked.url)
+            throw new Error(`The store's answer named no address for ${file.name}: give uploadTo a link() that reads it`);
+        return { url: linked.url, name: linked.name ?? file.name, size: linked.size ?? file.size, type: linked.type ?? file.type, ...(linked.fileId !== undefined ? { fileId: linked.fileId } : {}) };
+    };
+}
+function viaXhr(host, sending) {
+    const { request } = sending;
+    return new Promise((resolve, reject) => {
+        const xhr = new host.XMLHttpRequest();
+        const stop = () => xhr.abort();
+        const done = () => request.signal?.removeEventListener('abort', stop);
+        xhr.open(sending.method, sending.url);
+        for (const [name, value] of Object.entries(sending.headers))
+            xhr.setRequestHeader(name, value);
+        if (sending.withCredentials)
+            xhr.withCredentials = true;
+        xhr.upload.onprogress = (event) => request.onProgress?.(event.loaded, event.lengthComputable ? event.total : sending.file.size);
+        xhr.onload = () => (done(), resolve(answered(sending.url, xhr.status, xhr.responseText, (name) => xhr.getResponseHeader(name))));
+        // What fetch throws when the network fails: read as the network's problem.
+        xhr.onerror = () => (done(), reject(new TypeError('Failed to fetch: the network failed during the upload')));
+        xhr.onabort = () => (done(), reject(stopped()));
+        request.signal?.addEventListener('abort', stop);
+        xhr.send(sending.body);
+    });
+}
+async function viaFetch(host, sending) {
+    if (!host.fetch)
+        throw new Error('uploadTo needs XMLHttpRequest or fetch');
+    const response = await host.fetch(sending.url, {
+        method: sending.method,
+        headers: sending.headers,
+        body: sending.body,
+        ...(sending.request.signal ? { signal: sending.request.signal } : {}),
+        ...(sending.withCredentials ? { credentials: 'include' } : {}),
+    });
+    const text = await response.text();
+    // No progress on the way: the whole of it, once it is there.
+    sending.request.onProgress?.(sending.file.size, sending.file.size);
+    return answered(sending.url, response.status, text, (name) => response.headers.get(name));
+}
+function answered(url, status, text, header) {
+    let json;
+    try {
+        json = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        json = undefined;
+    }
+    return { status, url, text, json, header };
+}
+/** What a refusing server says, for the person: its JSON's message, or a short text. */
+function wordsOf(answer) {
+    const json = answer.json;
+    const said = json?.message ?? (typeof json?.error === 'object' ? json.error?.message : json?.error);
+    if (typeof said === 'string' && said.trim())
+        return said.trim();
+    const text = answer.text.trim();
+    return text && text.length <= 200 && !/^\s*</.test(text) && answer.json === undefined ? text : '';
+}
+/** The stored file's address as the answer gives it: JSON, Location, or where a PUT put it. */
+function linkOf(answer, method, host) {
+    const json = (answer.json && typeof answer.json === 'object' ? answer.json : {});
+    const id = json['fileId'] ?? json['id'];
+    const fileId = typeof id === 'string' || typeof id === 'number' ? id : undefined;
+    const said = json['url'] ?? json['location'];
+    const location = answer.header('location');
+    const url = typeof said === 'string' ? said : location ? against(location, answer.url, host) : method === 'PUT' ? answer.url.split('?')[0] : undefined;
+    return { ...(url ? { url } : {}), ...(fileId !== undefined ? { fileId } : {}) };
+}
+/** A Location read against the address the file was sent to. */
+function against(location, sentTo, host) {
+    try {
+        return new host.URL(location, new host.URL(sentTo, host.location?.href).href).href;
+    }
+    catch {
+        return location;
+    }
+}
+//# sourceMappingURL=upload-to.mjs.map

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 {};