@koolbase/core 12.17.0 → 12.19.0

package/dist/cjs/storage-transfer.d.ts

@@ -33,6 +33,7 @@ export declare class KoolbaseUploadTask {
     private cancelRequested;
     private abortTransfer;
     private total;
+    private _uploadId;
     /**
      * The uploaded file. Rejects with `KoolbaseUploadCancelledError` if it was
      * cancelled, or the error that made it fail.
@@ -44,6 +45,15 @@ export declare class KoolbaseUploadTask {
     constructor();
     /** Where the upload is now. */
     get current(): KoolbaseUploadProgress;
+    /**
+     * A large file's upload goes in parts, and can be resumed for a day: keep
+     * this id, and pass it to `KoolbaseStorage.resumeUpload` with the same
+     * file after the app restarts or the upload fails. Null for a file sent
+     * in one piece, and until the upload has begun.
+     */
+    get uploadId(): string | null;
+    /** @internal */
+    setUploadId(id: string): void;
     /**
      * Calls `listener` on every change of state and every chunk sent, starting
      * with where the upload is now. Returns a function that stops it.
@@ -74,15 +84,24 @@ export declare class KoolbaseUploadTask {
 }
 /** Runs `body` as the task's upload, starting on the next turn so a caller can listen to every event. */
 export declare function runUploadTask(body: (task: KoolbaseUploadTask) => Promise<UploadResult>): KoolbaseUploadTask;
-interface PutResult {
+export interface PutResult {
     status: number;
     etag: string;
 }
+/** A PUT under way: its outcome, and how to stop it. */
+export interface Transfer {
+    done: Promise<PutResult>;
+    abort(): void;
+}
+/**
+ * PUTs `body` to `url`, reporting bytes as they are sent. XMLHttpRequest
+ * where the host has it (browsers and React Native both report upload
+ * progress); fetch elsewhere, where progress jumps from 0 to the total.
+ * An aborted transfer rejects with `KoolbaseUploadCancelledError`.
+ */
+export declare function transferBytes(url: string, body: Blob, contentType: string | null, onSent: (sent: number) => void): Transfer;
 /**
- * Sends `body` to a presigned `url` with PUT, reporting bytes as they are
- * sent. XMLHttpRequest where the host has it (browsers and React Native,
- * both report upload progress); fetch elsewhere, where progress jumps from
- * 0 to the total. A cancel aborts it.
+ * Sends `body` to a presigned `url` with PUT as the task's one transfer,
+ * reporting bytes as they are sent; a cancel aborts it.
  */
 export declare function putWithProgress(task: KoolbaseUploadTask, url: string, body: Blob, contentType: string): Promise<PutResult>;
-export {};

package/dist/cjs/storage-transfer.js

@@ -9,6 +9,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseUploadTask = void 0;
 exports.runUploadTask = runUploadTask;
+exports.transferBytes = transferBytes;
 exports.putWithProgress = putWithProgress;
 const network_js_1 = require("./network.js");
 const storage_errors_js_1 = require("./storage-errors.js");
@@ -37,6 +38,7 @@ class KoolbaseUploadTask {
         this.cancelRequested = false;
         this.abortTransfer = null;
         this.total = 0;
+        this._uploadId = null;
         this._current = progressOf('pending', 0, 0);
         this.result = new Promise((res, rej) => {
             this.resolve = res;
@@ -50,6 +52,19 @@ class KoolbaseUploadTask {
     get current() {
         return this._current;
     }
+    /**
+     * A large file's upload goes in parts, and can be resumed for a day: keep
+     * this id, and pass it to `KoolbaseStorage.resumeUpload` with the same
+     * file after the app restarts or the upload fails. Null for a file sent
+     * in one piece, and until the upload has begun.
+     */
+    get uploadId() {
+        return this._uploadId;
+    }
+    /** @internal */
+    setUploadId(id) {
+        this._uploadId = id;
+    }
     /**
      * Calls `listener` on every change of state and every chunk sent, starting
      * with where the upload is now. Returns a function that stops it.
@@ -145,70 +160,96 @@ function runUploadTask(body) {
     return task;
 }
 /**
- * Sends `body` to a presigned `url` with PUT, reporting bytes as they are
- * sent. XMLHttpRequest where the host has it (browsers and React Native,
- * both report upload progress); fetch elsewhere, where progress jumps from
- * 0 to the total. A cancel aborts it.
+ * PUTs `body` to `url`, reporting bytes as they are sent. XMLHttpRequest
+ * where the host has it (browsers and React Native both report upload
+ * progress); fetch elsewhere, where progress jumps from 0 to the total.
+ * An aborted transfer rejects with `KoolbaseUploadCancelledError`.
  */
-function putWithProgress(task, url, body, contentType) {
-    task.checkCancelled();
-    const total = body.size;
-    const report = (sent) => {
-        if (!task.cancelled)
-            task.emit('uploading', Math.min(sent, total));
-    };
-    report(0);
+function transferBytes(url, body, contentType, onSent) {
     const XHR = globalThis.XMLHttpRequest;
     if (XHR) {
-        return new Promise((resolve, reject) => {
-            const xhr = new XHR();
-            let settled = false;
-            const done = (fn) => {
+        const xhr = new XHR();
+        let settled = false;
+        let fail = () => undefined;
+        const done = new Promise((resolve, reject) => {
+            const finish = (fn) => {
                 if (settled)
                     return;
                 settled = true;
-                task.setAbort(null);
                 fn();
             };
+            fail = (e) => finish(() => reject(e));
             xhr.open('PUT', url);
-            xhr.setRequestHeader('Content-Type', contentType);
+            if (contentType)
+                xhr.setRequestHeader('Content-Type', contentType);
             if (xhr.upload) {
-                xhr.upload.onprogress = (ev) => report(ev.loaded);
+                xhr.upload.onprogress = (ev) => onSent(Math.min(ev.loaded, body.size));
             }
-            xhr.onload = () => done(() => {
-                if (task.cancelled)
-                    return reject(new storage_errors_js_1.KoolbaseUploadCancelledError());
-                resolve({ status: xhr.status, etag: xhr.getResponseHeader('etag') ?? '' });
-            });
-            xhr.onerror = () => done(() => reject(task.cancelled ? new storage_errors_js_1.KoolbaseUploadCancelledError() : new network_js_1.KoolbaseNetworkError(url, new Error('the upload did not complete'))));
-            xhr.onabort = () => done(() => reject(new storage_errors_js_1.KoolbaseUploadCancelledError()));
-            task.setAbort(() => {
-                xhr.abort();
-                // Some hosts do not fire onabort for an aborted send.
-                done(() => reject(new storage_errors_js_1.KoolbaseUploadCancelledError()));
-            });
+            xhr.onload = () => finish(() => resolve({ status: xhr.status, etag: xhr.getResponseHeader('etag') ?? '' }));
+            xhr.onerror = () => fail(new network_js_1.KoolbaseNetworkError(url, new Error('the upload did not complete')));
+            xhr.onabort = () => fail(new storage_errors_js_1.KoolbaseUploadCancelledError());
+            onSent(0);
             xhr.send(body);
         });
+        return {
+            done,
+            abort: () => {
+                xhr.abort();
+                // Some hosts do not fire onabort for an aborted send.
+                fail(new storage_errors_js_1.KoolbaseUploadCancelledError());
+            },
+        };
     }
     const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
-    task.setAbort(() => controller?.abort());
-    return fetch(url, {
+    let aborted = false;
+    onSent(0);
+    const done = fetch(url, {
         method: 'PUT',
-        headers: { 'Content-Type': contentType },
+        headers: contentType ? { 'Content-Type': contentType } : {},
         body,
         signal: controller?.signal,
     })
         .then((res) => {
-        task.checkCancelled();
+        if (aborted)
+            throw new storage_errors_js_1.KoolbaseUploadCancelledError();
+        onSent(body.size);
         return { status: res.status, etag: res.headers.get('etag') ?? '' };
     })
         .catch((e) => {
-        if (task.cancelled || e?.name === 'AbortError') {
+        if (aborted || e?.name === 'AbortError')
             throw new storage_errors_js_1.KoolbaseUploadCancelledError();
-        }
         if (e instanceof storage_errors_js_1.KoolbaseStorageError)
             throw e;
         throw new network_js_1.KoolbaseNetworkError(url, e);
+    });
+    return {
+        done,
+        abort: () => {
+            aborted = true;
+            controller?.abort();
+        },
+    };
+}
+/**
+ * Sends `body` to a presigned `url` with PUT as the task's one transfer,
+ * reporting bytes as they are sent; a cancel aborts it.
+ */
+function putWithProgress(task, url, body, contentType) {
+    task.checkCancelled();
+    const total = body.size;
+    const report = (sent) => {
+        if (!task.cancelled)
+            task.emit('uploading', Math.min(sent, total));
+    };
+    const t = transferBytes(url, body, contentType, report);
+    task.setAbort(() => t.abort());
+    return t.done
+        .then((r) => {
+        task.checkCancelled();
+        return r;
+    })
+        .catch((e) => {
+        throw task.cancelled ? new storage_errors_js_1.KoolbaseUploadCancelledError() : e;
     })
         .finally(() => task.setAbort(null));
 }

package/dist/cjs/storage.d.ts

@@ -72,6 +72,46 @@ export declare class KoolbaseStorage {
      */
     startUpload(options: UploadOptions): KoolbaseUploadTask;
     private runUpload;
+    /**
+     * Files larger than this go up in parts (S3): each part retried on its
+     * own, the upload resumable for a day with `resumeUpload`. 16 MiB.
+     */
+    static multipartThreshold: number;
+    /**
+     * Resumes a large file's upload that failed or was interrupted -- the
+     * network dropped, the app was closed -- sending only the parts that did
+     * not arrive. `uploadId` is the failed task's `uploadId`; `file` must be
+     * the same file. Within a day of the upload beginning.
+     *
+     * @example
+     * const task = Koolbase.storage.startUpload({ bucket: 'video', path: 'talk.mp4', file });
+     * saveForLater(task.uploadId); // once the upload has begun
+     * // ... after a restart:
+     * await Koolbase.storage.resumeUpload({ bucket: 'video', uploadId, file }).result;
+     */
+    resumeUpload(options: {
+        bucket: string;
+        uploadId: string;
+        file: UploadOptions['file'];
+        metadata?: Record<string, string>;
+        overwrite?: boolean;
+    }): KoolbaseUploadTask;
+    private runInParts;
+    /**
+     * Downloads a file's bytes, reporting them as they arrive (S3):
+     * `onProgress(received, total)`, total null when the size is not known.
+     * Aborting `signal` stops it with `KoolbaseDownloadCancelledError`.
+     *
+     * @example
+     * const blob = await Koolbase.storage.download({ bucket: 'video', path: 'talk.mp4', onProgress: (r, t) => setPct(t ? r / t : 0) });
+     */
+    download(options: {
+        bucket: string;
+        path: string;
+        versionId?: string;
+        onProgress?: (received: number, total: number | null) => void;
+        signal?: AbortSignal;
+    }): Promise<Blob>;
     /**
      * One page of a bucket's files. The bucket's view rule is applied to every
      * file: the page holds only files the signed-in person may view. Pass the

package/dist/cjs/storage.js

@@ -6,7 +6,16 @@ const network_js_1 = require("./network.js");
 const errors_js_1 = require("./errors.js");
 const storage_errors_js_2 = require("./storage-errors.js");
 const storage_transfer_js_1 = require("./storage-transfer.js");
+const storage_multipart_js_1 = require("./storage-multipart.js");
+const storage_errors_js_3 = require("./storage-errors.js");
+const files_refresh_js_1 = require("./files-refresh.js");
+const network_js_2 = require("./network.js");
 const storage_files_js_1 = require("./storage-files.js");
+/** An upload task whose success reloads the bucket's file lists (storage S4). */
+function listsReload(task, bucket) {
+    task.result.then(() => { void (0, files_refresh_js_1.refreshBucketFiles)(bucket); }, () => { });
+    return task;
+}
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -129,7 +138,7 @@ class KoolbaseStorage {
      * const { object } = await task.result;
      */
     startUpload(options) {
-        return (0, storage_transfer_js_1.runUploadTask)((task) => this.runUpload(options, task));
+        return listsReload((0, storage_transfer_js_1.runUploadTask)((task) => this.runUpload(options, task)), options.bucket);
     }
     async runUpload(options, task) {
         task.checkCancelled();
@@ -144,6 +153,19 @@ class KoolbaseStorage {
             : options.file.type;
         if (isBlob)
             task.setTotal(options.file.size);
+        // A browser hands us the bytes already: a File from an input is a Blob,
+        // and fetching its .uri would be fetching undefined. React Native hands
+        // us a local URI, and its fetch resolves that into a Blob -- read first,
+        // since its size decides how it is sent (S3).
+        const fileBlob = isBlob
+            ? options.file
+            : await (await (0, network_js_1.sessionFetch)(options.file.uri)).blob();
+        task.setTotal(fileBlob.size);
+        task.checkCancelled();
+        // Large files go in parts: resumable, each part retried (S3).
+        if (fileBlob.size > KoolbaseStorage.multipartThreshold) {
+            return this.runInParts(options.bucket, options, task, fileBlob, contentType, null);
+        }
         // ─── Step 1: Get presigned upload URL ───
         const urlRes = await (0, network_js_1.sessionFetch)(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
             method: 'POST',
@@ -165,16 +187,7 @@ class KoolbaseStorage {
         task.checkCancelled();
         // ─── Step 2: Upload directly to R2 ───
         // R2 presigned URLs expect raw binary, NOT multipart/form-data.
-        //
-        // A browser hands us the bytes already: a File from an input is a Blob,
-        // and fetching its .uri would be fetching undefined. React Native hands
-        // us a local URI, and its fetch resolves that into a Blob — which is why
-        // the two hosts differ here and nowhere else in this method.
-        const fileBlob = isBlob
-            ? options.file
-            : await (await (0, network_js_1.sessionFetch)(options.file.uri)).blob();
         const fileSize = fileBlob.size;
-        task.setTotal(fileSize);
         const uploadRes = await (0, storage_transfer_js_1.putWithProgress)(task, upload_url, fileBlob, contentType);
         if (uploadRes.status < 200 || uploadRes.status >= 300) {
             // R2 PUT errors don't follow the Koolbase error shape — surface as a
@@ -222,6 +235,173 @@ class KoolbaseStorage {
         const downloadUrl = await this.getDownloadUrl(options.bucket, options.path);
         return { object, downloadUrl };
     }
+    /**
+     * Resumes a large file's upload that failed or was interrupted -- the
+     * network dropped, the app was closed -- sending only the parts that did
+     * not arrive. `uploadId` is the failed task's `uploadId`; `file` must be
+     * the same file. Within a day of the upload beginning.
+     *
+     * @example
+     * const task = Koolbase.storage.startUpload({ bucket: 'video', path: 'talk.mp4', file });
+     * saveForLater(task.uploadId); // once the upload has begun
+     * // ... after a restart:
+     * await Koolbase.storage.resumeUpload({ bucket: 'video', uploadId, file }).result;
+     */
+    resumeUpload(options) {
+        return listsReload((0, storage_transfer_js_1.runUploadTask)(async (task) => {
+            const isBlob = typeof Blob !== 'undefined' && options.file instanceof Blob;
+            const blob = isBlob
+                ? options.file
+                : await (await (0, network_js_1.sessionFetch)(options.file.uri)).blob();
+            task.setTotal(blob.size);
+            return this.runInParts(options.bucket, options, task, blob, '', options.uploadId);
+        }), options.bucket);
+    }
+    async runInParts(bucket, options, task, file, contentType, resumeId) {
+        const base = `${this.config.baseUrl}/v1/sdk/storage/uploads`;
+        const json = async () => ({ ...(await this.buildHeaders()), 'Content-Type': 'application/json' });
+        const overwrite = options.overwrite ?? false;
+        let plan;
+        if (resumeId) {
+            const res = await (0, network_js_1.sessionFetch)(`${base}?bucket=${encodeURIComponent(bucket)}&upload_id=${encodeURIComponent(resumeId)}`, {
+                headers: await this.buildHeaders(),
+            });
+            if (!res.ok)
+                throw await this.error(res, 'Failed to resume the upload');
+            plan = (await res.json());
+            if (plan.size !== file.size) {
+                throw new storage_errors_js_2.KoolbaseStorageError(`This is not the file the upload began with: it has ${file.size} bytes, the upload ${plan.size}`, 'validation_error');
+            }
+        }
+        else {
+            const res = await (0, network_js_1.sessionFetch)(base, {
+                method: 'POST',
+                headers: await json(),
+                body: JSON.stringify({ bucket, path: options.path, content_type: contentType, size: file.size, overwrite }),
+            });
+            if (!res.ok)
+                throw await this.error(res, 'Failed to begin the upload');
+            plan = (await res.json());
+        }
+        task.setUploadId(plan.upload_id);
+        task.checkCancelled();
+        await (0, storage_multipart_js_1.sendParts)(task, plan, file, {
+            links: async (parts) => {
+                const res = await (0, network_js_1.sessionFetch)(`${base}/parts`, {
+                    method: 'POST',
+                    headers: await json(),
+                    body: JSON.stringify({ bucket, upload_id: plan.upload_id, parts }),
+                });
+                if (!res.ok)
+                    throw await this.error(res, 'Failed to get upload links');
+                return (await res.json()).links;
+            },
+            abort: async () => {
+                await (0, network_js_1.sessionFetch)(base, {
+                    method: 'DELETE',
+                    headers: await json(),
+                    body: JSON.stringify({ bucket, upload_id: plan.upload_id }),
+                });
+            },
+        });
+        // The parts have arrived: the server joins and checks them. No longer
+        // cancellable.
+        task.verifying();
+        const body = { bucket, upload_id: plan.upload_id, overwrite };
+        if (options.metadata !== undefined)
+            body.metadata = options.metadata;
+        const done = await (0, network_js_1.sessionFetch)(`${base}/complete`, { method: 'POST', headers: await json(), body: JSON.stringify(body) });
+        if (!done.ok)
+            throw await this.error(done, 'Failed to complete the upload');
+        const object = mapObjectFromServer(await done.json());
+        const downloadUrl = await this.getDownloadUrl(bucket, object.path);
+        return { object, downloadUrl };
+    }
+    /**
+     * Downloads a file's bytes, reporting them as they arrive (S3):
+     * `onProgress(received, total)`, total null when the size is not known.
+     * Aborting `signal` stops it with `KoolbaseDownloadCancelledError`.
+     *
+     * @example
+     * const blob = await Koolbase.storage.download({ bucket: 'video', path: 'talk.mp4', onProgress: (r, t) => setPct(t ? r / t : 0) });
+     */
+    async download(options) {
+        if (options.signal?.aborted)
+            throw new storage_errors_js_3.KoolbaseDownloadCancelledError();
+        const url = await this.getDownloadUrl(options.bucket, options.path, options.versionId);
+        const report = options.onProgress ?? (() => undefined);
+        const XHR = globalThis.XMLHttpRequest;
+        if (XHR) {
+            return new Promise((resolve, reject) => {
+                const xhr = new XHR();
+                let settled = false;
+                const finish = (fn) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    options.signal?.removeEventListener('abort', stop);
+                    fn();
+                };
+                const stop = () => {
+                    xhr.abort();
+                    finish(() => reject(new storage_errors_js_3.KoolbaseDownloadCancelledError()));
+                };
+                options.signal?.addEventListener('abort', stop);
+                xhr.open('GET', url);
+                xhr.responseType = 'blob';
+                xhr.onprogress = (ev) => report(ev.loaded, ev.lengthComputable ? ev.total : null);
+                xhr.onload = () => finish(() => {
+                    if (xhr.status < 200 || xhr.status >= 300) {
+                        reject(new storage_errors_js_2.KoolbaseStorageError(`Download failed: ${xhr.status}`));
+                        return;
+                    }
+                    const blob = xhr.response;
+                    report(blob.size, blob.size);
+                    resolve(blob);
+                });
+                xhr.onerror = () => finish(() => reject(new network_js_2.KoolbaseNetworkError(url, new Error('the download did not complete'))));
+                xhr.onabort = () => finish(() => reject(new storage_errors_js_3.KoolbaseDownloadCancelledError()));
+                xhr.send();
+            });
+        }
+        let res;
+        try {
+            res = await fetch(url, { signal: options.signal });
+        }
+        catch (e) {
+            if (options.signal?.aborted)
+                throw new storage_errors_js_3.KoolbaseDownloadCancelledError();
+            throw new network_js_2.KoolbaseNetworkError(url, e);
+        }
+        if (!res.ok)
+            throw new storage_errors_js_2.KoolbaseStorageError(`Download failed: ${res.status}`);
+        const total = Number(res.headers.get('content-length')) || null;
+        const reader = res.body?.getReader?.();
+        if (!reader) {
+            const blob = await res.blob();
+            report(blob.size, blob.size);
+            return blob;
+        }
+        const chunks = [];
+        let received = 0;
+        report(0, total);
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                chunks.push(value);
+                received += value.length;
+                report(received, total);
+            }
+        }
+        catch (e) {
+            if (options.signal?.aborted)
+                throw new storage_errors_js_3.KoolbaseDownloadCancelledError();
+            throw new network_js_2.KoolbaseNetworkError(url, e);
+        }
+        return new Blob(chunks, { type: res.headers.get('content-type') ?? '' });
+    }
     /**
      * One page of a bucket's files. The bucket's view rule is applied to every
      * file: the page holds only files the signed-in person may view. Pass the
@@ -292,7 +472,9 @@ class KoolbaseStorage {
         if (!res.ok) {
             throw await this.error(res, op === 'move' ? 'Failed to move the file' : 'Failed to copy the file');
         }
-        return mapObjectFromServer(await res.json());
+        const moved = mapObjectFromServer(await res.json());
+        void (0, files_refresh_js_1.refreshBucketFiles)(o.bucket, ...(o.toBucket && o.toBucket !== o.bucket ? [o.toBucket] : []));
+        return moved;
     }
     /**
      * Apply a partial metadata update to an existing object. Returns the
@@ -340,6 +522,7 @@ class KoolbaseStorage {
             throw await this.error(res, 'Failed to update metadata');
         }
         const raw = await res.json();
+        void (0, files_refresh_js_1.refreshBucketFiles)(bucket);
         return mapObjectFromServer(raw);
     }
     /**
@@ -471,11 +654,11 @@ class KoolbaseStorage {
             },
             body: JSON.stringify({ bucket, path }),
         });
-        if (res.status === 204)
+        if (res.ok) {
+            void (0, files_refresh_js_1.refreshBucketFiles)(bucket);
             return;
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to delete file');
         }
+        throw await this.error(res, 'Failed to delete file');
     }
     /**
      * List all versions of a file path, newest-first. Returns a flat list
@@ -532,7 +715,9 @@ class KoolbaseStorage {
         if (!res.ok) {
             throw await this.error(res, 'Failed to restore version');
         }
-        return mapObjectFromServer(await res.json());
+        const restored = mapObjectFromServer(await res.json());
+        void (0, files_refresh_js_1.refreshBucketFiles)(bucket);
+        return restored;
     }
     /**
      * Hard-remove a single history version — both the metadata row and
@@ -555,6 +740,11 @@ class KoolbaseStorage {
     }
 }
 exports.KoolbaseStorage = KoolbaseStorage;
+/**
+ * Files larger than this go up in parts (S3): each part retried on its
+ * own, the upload resumable for a day with `resumeUpload`. 16 MiB.
+ */
+KoolbaseStorage.multipartThreshold = 16 * 1024 * 1024;
 /**
  * Maps the snake_case server JSON to the camelCase {@link KoolbaseObject}.
  * Defensive: missing or null `metadata` (older / non-Koolbase responses)

package/dist/esm/files-controller.d.ts

@@ -0,0 +1,62 @@
+import type { KoolbaseFileInfo, KoolbaseFilePage, KoolbaseFileSort, ListFilesOptions } from './storage-files.js';
+export type FilesStatus = 'loading' | 'loaded' | 'error';
+/** Which files, in what order. The bucket's view rule decides the rest. */
+export interface FilesQuery {
+    /** Only files whose path starts with this, taken literally. */
+    prefix?: string;
+    /** By path unless set. */
+    sort?: KoolbaseFileSort;
+    /** Z to A, newest first, largest first. */
+    descending?: boolean;
+    /** Files per page: 50 unless set, at most 100. */
+    limit?: number;
+}
+export interface FilesState {
+    readonly status: FilesStatus;
+    readonly files: readonly KoolbaseFileInfo[];
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+    /** True while loadMore() runs. */
+    readonly loadingMore: boolean;
+    /** Whether there is a page past the last one loaded. True before the first load. */
+    readonly hasMore: boolean;
+}
+export declare const initialFilesState: FilesState;
+/** One string per distinct listing. */
+export declare function filesQueryKey(bucket: string, query?: FilesQuery): string;
+type FilesReader = {
+    listFiles(options: ListFilesOptions): Promise<KoolbaseFilePage>;
+};
+export declare class KoolbaseFilesController {
+    readonly bucket: string;
+    private readonly storage;
+    private readonly spec;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    private pageOne;
+    private laterPages;
+    private cursor;
+    private unregister;
+    constructor(storage: FilesReader, bucket: string, query?: FilesQuery);
+    getState(): FilesState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** Page one again. What is shown stays while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /** The next page, appended. Does nothing unless loaded with a page to come. */
+    loadMore(): Promise<void>;
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose(): void;
+    private firstPage;
+    private publish;
+    private options;
+    private isStale;
+    private set;
+}
+export {};