@tinvar/react 0.0.0-stage → 0.4.1

package/src/upload.d.ts

@@ -0,0 +1,342 @@
+import type { ReactNode, RefObject } from 'react';
+
+export declare const UPLOAD_PATH: '/_upload';
+
+/** Where a ticket a page has outlived is issued again. */
+export declare const UPLOAD_REFRESH_PATH: '/_upload/refresh';
+export declare const UPLOAD_DIRECT_PATH: '/_upload/direct';
+export declare const UPLOAD_COMPLETE_PATH: '/_upload/complete';
+
+/** Where a resumable upload begins, under the ticket (ADR 0143). */
+export declare const UPLOAD_SESSION_PATH: '/_upload/session';
+/** Where it is asked how much of a resumable upload the server holds. */
+export declare const UPLOAD_OFFSET_PATH: '/_upload/session/offset';
+/** Where a chunk is appended through PHP, at the offset the server holds. */
+export declare const UPLOAD_CHUNK_PATH: '/_upload/session/chunk';
+/** Where the URLs for the next parts to the store are asked for. */
+export declare const UPLOAD_PARTS_PATH: '/_upload/session/parts';
+/** Where an upload sent in parts is completed. */
+export declare const UPLOAD_SESSION_COMPLETE_PATH: '/_upload/session/complete';
+/** Where a resumable upload is given up, its room given back. */
+export declare const UPLOAD_ABORT_PATH: '/_upload/session/abort';
+
+/**
+ * Gives a resumable upload's session up on the server -- its bytes removed,
+ * its room given back -- whatever the server answers. The record that
+ * remembers it is the caller's to delete from its resume store.
+ */
+export declare function abortUpload(session: string): Promise<void>;
+
+/**
+ * What a resumable upload remembers across a refresh, in IndexedDB: the
+ * session the server signed and the file's name, size and fingerprint --
+ * never its bytes -- and, where the browser has one, a handle to reopen it.
+ */
+export interface ResumeRecord {
+  id: string;
+  scope: string;
+  fingerprint: string;
+  session: string;
+  mode: 'chunks' | 'parts';
+  name: string;
+  size: number;
+  type: string;
+  lastModified: number;
+  offset: number;
+  createdAt: number;
+  /** Seconds since the epoch, as the server set it. */
+  expiresAt: number;
+  handle?: unknown;
+}
+
+/** Where resumable uploads are remembered. Every method settles; none throws. */
+export interface ResumeStore {
+  /** Forgets every record unless the store's are already the session and user $binding (the router's) names; all of them for null. */
+  purge?(binding: string | null): Promise<void>;
+  get(id: string): Promise<ResumeRecord | null>;
+  put(record: ResumeRecord): Promise<void>;
+  delete(id: string): Promise<void>;
+  inScope(scope: string): Promise<ResumeRecord[]>;
+}
+
+/** The browser's resume store, in IndexedDB; one that remembers nothing where IndexedDB cannot be had. */
+export declare function indexedDbResumeStore(): ResumeStore;
+/** A resume store in memory, for tests. */
+export declare function memoryResumeStore(): ResumeStore;
+
+/** Where a resumable upload stands, while it is going: sending, waiting out a dropped network, or asking where to go on. */
+export type ResumableState = 'uploading' | 'paused' | 'resuming';
+
+/** The session a resumable upload goes on in, and the id of the record that remembers it (null where none does). */
+export interface ResumableSession {
+  session: string;
+  id: string | null;
+}
+
+export interface UploadProgress {
+  loaded: number;
+  total: number | undefined;
+  percentage: number | undefined;
+}
+
+/** What /_upload answered: the reference the form sends, and the file as the server saw it. */
+export interface Uploaded {
+  /** Opaque: what the action parameter is posted as. */
+  upload: string;
+  /** What the client called the file, cleaned: metadata only. */
+  name: string;
+  size: number;
+  /** The type the server sniffed the bytes as. */
+  type: string;
+}
+
+/**
+ * Why an upload did not go in, for the app to say in its own words:
+ * `too_large` (413), `type` (the bytes are not a type the field takes,
+ * 415), `invalid` (empty, or no file, 422), `refused` (the ticket has run
+ * out, or is not this session's -- reload the page, 403), `signed_out`
+ * (401), `throttled` (429), `quota` (the user's files fill their quota, 507),
+ * `infected` (a scanner found malware in it, 422), `unavailable` (it could
+ * not be scanned, 503),
+ * `expired` (the page outlived its session, 419),
+ * `network`, or `failed`.
+ */
+export type UploadErrorKind =
+  | 'too_large'
+  | 'type'
+  | 'invalid'
+  | 'refused'
+  | 'signed_out'
+  | 'throttled'
+  | 'quota'
+  | 'infected'
+  | 'unavailable'
+  | 'expired'
+  | 'network'
+  | 'failed';
+
+export interface UploadError {
+  kind: UploadErrorKind;
+  status: number;
+  code: string | null;
+  /** The digest to quote to support, when the server gave one. */
+  reference: string | null;
+  retryAfter: number | null;
+}
+
+export type UploadOutcome =
+  { type: 'uploaded'; file: Uploaded } | { type: 'error'; error: UploadError } | { type: 'cancelled' };
+
+export interface UploadOptions {
+  ticket: string;
+  file: Blob;
+  url?: string;
+  /** Refuses a larger file without sending it; the server holds the real limit. */
+  maxBytes?: number;
+  signal?: AbortSignal;
+  onProgress?: (progress: UploadProgress) => void;
+  /** Asks for the ticket again once, on a refusal, and sends the file again under it. */
+  refresh?: boolean;
+  refreshUrl?: string;
+  /** Told the ticket a refresh issued, for the uploads after this one. */
+  onTicket?: (ticket: string) => void;
+  /**
+   * Sends the file straight to the application's object store, by a URL
+   * /_upload/direct presigns for its size, and has /_upload/complete check
+   * and keep it. The bucket must allow this origin's PUT.
+   */
+  direct?: boolean;
+  /**
+   * Sends it as a resumable upload (ADR 0143): in chunks through PHP, or --
+   * with `direct` -- in parts to the store, each from the byte the server
+   * holds. A dropped network is waited out; the same file sent again after
+   * a refresh goes on from where the server is. A server that takes none
+   * has it sent whole.
+   */
+  resumable?: boolean;
+  /** Told when a resumable upload pauses for the network, asks where to go on, and sends again. */
+  onState?: (state: ResumableState) => void;
+  /**
+   * Told the session a resumable upload goes on in, once it is known. A
+   * cancel through `signal` keeps it on the server for a later page to go
+   * on with; a caller giving the upload up for good gives it up too.
+   */
+  onSession?: (session: ResumableSession) => void;
+  /** A FileSystemFileHandle the file was chosen through, kept so it can be reopened after a refresh. */
+  handle?: unknown;
+  /** Where resumable uploads are remembered: IndexedDB unless given. */
+  resumeStore?: ResumeStore;
+  /** Seconds between tries after a network drop or a 5xx. */
+  backoff?: number[];
+}
+
+/** Sends one file to /_upload under a ticket. Never throws for an outcome. */
+export declare function uploadFile(options: UploadOptions): Promise<UploadOutcome>;
+
+export type RefreshOutcome =
+  | { type: 'refreshed'; ticket: string; expiresAt: number }
+  | { type: 'error'; error: UploadError }
+  | { type: 'cancelled' };
+
+/**
+ * Asks for a ticket the page holds to be issued again: for the same
+ * session, user, action and record, for another hour, and never past a day
+ * from its first issue.
+ */
+export declare function refreshTicket(options: {
+  ticket: string;
+  url?: string;
+  signal?: AbortSignal;
+}): Promise<RefreshOutcome>;
+
+export type UploadStatus = 'idle' | 'uploading' | 'paused' | 'resuming' | 'uploaded' | 'error';
+
+export interface UseUploadOptions {
+  /** The ticket the page's loader issued for this action parameter. */
+  ticket: string;
+  url?: string;
+  maxBytes?: number;
+  /** Runs once the reference is in state, so a submit from it sends it. */
+  onUploaded?: (file: Uploaded) => void;
+  onError?: (error: UploadError) => void;
+  /** Sends each file straight to the object store (see UploadOptions). */
+  direct?: boolean;
+  /** Sends each file as a resumable upload, and offers to go on with one a refresh interrupted (see UploadOptions). */
+  resumable?: boolean;
+  resumeStore?: ResumeStore;
+  backoff?: number[];
+}
+
+/** An upload of this field the server still holds part of, begun before a refresh, a closed tab or a crash. */
+export interface PendingUpload {
+  name: string;
+  size: number;
+  /** The bytes the server holds. */
+  offset: number;
+  percentage: number;
+  /** Whether the browser kept a handle to the file, so resuming asks only for permission to read it. */
+  reopenable: boolean;
+}
+
+export interface UploadState {
+  /** `paused` while a dropped network is waited out, `resuming` while the server is asked where to go on. */
+  status: UploadStatus;
+  /** True while it is sending, paused or resuming. */
+  uploading: boolean;
+  paused: boolean;
+  resuming: boolean;
+  progress: UploadProgress | null;
+  file: Uploaded | null;
+  error: UploadError | null;
+  /** What the form sends under the parameter's name, once the upload is in. */
+  reference: string | null;
+  /** With `resumable`: an upload the server still holds part of, to offer to go on with. */
+  pending: PendingUpload | null;
+  /** Uploads a file, cancelling one still going; the file it holds part of goes on from there. */
+  upload: (file: Blob, options?: { handle?: unknown }) => Promise<UploadOutcome>;
+  /**
+   * Goes on with `pending`: reopening the file where the browser kept a
+   * handle to it -- call it from a click, for the permission prompt -- and
+   * answering null where the person has to choose the file again.
+   */
+  resume: () => Promise<UploadOutcome | null>;
+  /** Gives up `pending`, on the server too: its bytes removed and its room given back. */
+  discardPending: () => Promise<void>;
+  /** Cancels the upload going; with `resumable`, gives its session up on the server too. */
+  cancel: () => void;
+  /** Empties the field, cancelling the upload going and, with `resumable`, giving its session up. */
+  reset: () => void;
+}
+
+/** One upload's state, for a field that takes one file. */
+export declare function useUpload(options: UseUploadOptions): UploadState;
+
+export interface UploadFieldSlot extends UploadState {
+  /** Opens the file input -- or, with `resumable`, the browser's own picker where it keeps a handle to the file. */
+  choose: () => void;
+  /** Goes on with `pending`, opening the picker for the person to choose the file again where it must. */
+  resume: () => Promise<UploadOutcome | null>;
+  /**
+   * Whether script runs. Until it does -- drawn by the server, or with no
+   * script at all -- the file input is named and the form, sent as
+   * multipart, posts the file to the action itself: show the input, and a
+   * button that submits the form.
+   */
+  scripted: boolean;
+  /** Props for the file input: named only until script runs, so script never posts the file. */
+  input: {
+    ref: RefObject<HTMLInputElement | null>;
+    type: 'file';
+    accept: string | undefined;
+    onChange: (event: { currentTarget: HTMLInputElement }) => void;
+    name: string | undefined;
+  };
+}
+
+export interface UploadFieldProps extends UseUploadOptions {
+  /** The action parameter the reference is posted as. */
+  name: string;
+  accept?: string;
+  children?: (field: UploadFieldSlot) => ReactNode;
+}
+
+/**
+ * A form field that uploads the file chosen in it to /_upload and posts the
+ * reference under `name`; it draws nothing but the hidden input.
+ */
+export declare function UploadField(props: UploadFieldProps): ReactNode;
+
+export interface UploadEntry {
+  key: number;
+  /** `paused` and `resuming` too, for a resumable upload. */
+  status: UploadStatus;
+  progress: UploadProgress | null;
+  file: Uploaded | null;
+  error: UploadError | null;
+}
+
+export interface UseUploadsOptions extends UseUploadOptions {
+  /** Refuses files past it without sending them; the server holds the real limit. */
+  maxFiles?: number;
+}
+
+export interface UploadsState {
+  entries: UploadEntry[];
+  uploading: boolean;
+  /** What the form sends under the parameter's name: a reference for each file that went in. */
+  references: string[];
+  /** Uploads each file, one after another, under the one ticket. */
+  upload: (files: Iterable<Blob>) => Promise<UploadOutcome[]>;
+  /** Drops a file: cancelled if it is going, never sent if queued; with `resumable`, its session given up. */
+  remove: (key: number) => void;
+  /** Drops every file, sending none still queued; with `resumable`, their sessions given up. */
+  reset: () => void;
+}
+
+/** The state of a parameter that takes several files (an UploadList). */
+export declare function useUploads(options: UseUploadsOptions): UploadsState;
+
+export interface UploadsFieldSlot extends UploadsState {
+  choose: () => void;
+  input: {
+    ref: RefObject<HTMLInputElement | null>;
+    type: 'file';
+    multiple: true;
+    accept: string | undefined;
+    onChange: (event: { currentTarget: HTMLInputElement }) => void;
+  };
+}
+
+export interface UploadsFieldProps extends UseUploadsOptions {
+  /** The action parameter the references are posted as, each under `name[]`. */
+  name: string;
+  accept?: string;
+  children?: (field: UploadsFieldSlot) => ReactNode;
+}
+
+/**
+ * A form field for a parameter that takes several files: it uploads each
+ * file chosen in it and posts every reference, drawing nothing but the
+ * hidden inputs.
+ */
+export declare function UploadsField(props: UploadsFieldProps): ReactNode;