@webx-ui/module-admin 0.19.0 → 0.20.0

package/dist/uploads.d.ts

@@ -0,0 +1,79 @@
+import { Ref } from 'vue';
+import { AdminContext } from './admin';
+/**
+ * Large files a piece at a time, through the panel's own four requests (§4 of the video spec):
+ *
+ *     POST   uploads        { name, size, type, fingerprint, purpose } → { id, offset, size, chunk_size }
+ *     HEAD   uploads/{id}   → Upload-Offset
+ *     PATCH  uploads/{id}   a piece, Upload-Offset: n → 204, Upload-Offset: n + length
+ *     DELETE uploads/{id}
+ *
+ * The server holds the offset and the client follows it: a 409 names where the file really
+ * ends, a HEAD asks after a dropped connection, and the same file chosen again after a reload
+ * finds its session by the fingerprint. What the server cannot know is the web server's own
+ * limit, so a 413 halves the piece — down to 256 KB — and the smaller piece stays for the rest
+ * of the file.
+ */
+export type ChunkedUploadState = 'idle' | 'uploading' | 'paused' | 'offline' | 'done' | 'failed';
+/** An upload that did not finish, as remembered in this browser for the next visit. */
+export interface UnfinishedUpload {
+    fingerprint: string;
+    purpose: string;
+    name: string;
+    size: number;
+    offset: number;
+    /** Milliseconds since the epoch, of the last piece that landed. */
+    updatedAt: number;
+}
+export interface ChunkedUploadOptions {
+    /** The panel to talk to; `useAdmin()` when left out. */
+    admin?: Pick<AdminContext, 'http' | 'apiPath'>;
+    /** Where unfinished uploads are remembered; `localStorage` when left out, `null` for nowhere. */
+    storage?: Storage | null;
+    /** How many times a piece lost to the network is sent again before the upload fails. */
+    retries?: number;
+    /** The wait before the first of those, doubled for each after it. */
+    retryDelay?: number;
+}
+export interface ChunkedUpload {
+    readonly state: Readonly<Ref<ChunkedUploadState>>;
+    /** 0 to 1. */
+    readonly progress: Readonly<Ref<number>>;
+    /** Bytes the server has. */
+    readonly uploaded: Readonly<Ref<number>>;
+    readonly total: Readonly<Ref<number>>;
+    /** Bytes a second, over the last few seconds; 0 until there is something to measure. */
+    readonly speed: Readonly<Ref<number>>;
+    /** Seconds left at that speed, or null while there is no speed to go by. */
+    readonly remaining: Readonly<Ref<number | null>>;
+    /** The session's id, which is what the module the file was for claims it by. */
+    readonly id: Readonly<Ref<string | null>>;
+    readonly error: Readonly<Ref<Error | null>>;
+    /**
+     * Send a file. Resolves with the session's id once the whole of it is on the server, with
+     * null when it is cancelled; rejects when it fails. A pause does neither — the same promise
+     * resolves once the upload is resumed and finished.
+     */
+    start(file: File, purpose: string): Promise<string | null>;
+    pause(): void;
+    /** Carry on after a pause, going offline or a failure; the promise of the upload. */
+    resume(): Promise<string | null>;
+    /** Stop and throw away what the server has. */
+    cancel(): Promise<void>;
+}
+/** The smallest piece the client falls back to on a 413 (the server never advises less). */
+export declare const MIN_CHUNK: number;
+/**
+ * What identifies a file without reading it: the same name, size and date of change is taken
+ * for the same file. Cheap on purpose — hashing gigabytes to find out where to resume would take
+ * longer than a good part of the upload.
+ */
+export declare function uploadFingerprint(file: Pick<File, 'name' | 'size' | 'lastModified'>): string;
+/**
+ * The uploads this browser started and did not finish — what a panel offers to continue after a
+ * reload ("choose the same file"). Empty wherever storage is refused.
+ */
+export declare function unfinishedUploads(purpose?: string, storage?: Storage | null): UnfinishedUpload[];
+/** Stop offering to continue an upload — the person chose not to. */
+export declare function forgetUnfinishedUpload(fingerprint: string, purpose: string, storage?: Storage | null): void;
+export declare function useChunkedUpload(options?: ChunkedUploadOptions): ChunkedUpload;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webx-ui/module-admin",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "The frame a WebX UI admin panel runs in: bootstrap, the shell, the HTTP client and the module registry that pairs with webx-ui/module-admin on the server.",
   "license": "MIT",
   "type": "module",