@koolbase/core 12.20.0 → 12.21.0

package/dist/cjs/index.d.ts

@@ -27,6 +27,8 @@ export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './fil
 export type { FilesQuery, FilesState, FilesStatus } from './files-controller.js';
 export { KoolbaseFileController, initialFileState } from './file-controller.js';
 export type { FileState, FileStatus } from './file-controller.js';
+export { KoolbaseUploadQueue, initialUploadQueueState } from './upload-queue.js';
+export type { KoolbaseUploader, QueuedUpload, QueuedUploadStatus, QueueFile, UploadQueueState } from './upload-queue.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';

package/dist/cjs/index.js

@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.initialFileState = exports.KoolbaseFileController = exports.filesQueryKey = exports.initialFilesState = exports.KoolbaseFilesController = exports.KoolbaseUploadTask = exports.KoolbaseStorage = exports.KoolbaseConnectivity = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
+exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.initialUploadQueueState = exports.KoolbaseUploadQueue = exports.initialFileState = exports.KoolbaseFileController = exports.filesQueryKey = exports.initialFilesState = exports.KoolbaseFilesController = exports.KoolbaseUploadTask = exports.KoolbaseStorage = exports.KoolbaseConnectivity = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./network.js"), exports);
@@ -62,6 +62,10 @@ Object.defineProperty(exports, "filesQueryKey", { enumerable: true, get: functio
 var file_controller_js_1 = require("./file-controller.js");
 Object.defineProperty(exports, "KoolbaseFileController", { enumerable: true, get: function () { return file_controller_js_1.KoolbaseFileController; } });
 Object.defineProperty(exports, "initialFileState", { enumerable: true, get: function () { return file_controller_js_1.initialFileState; } });
+// Several uploads in a queue (storage S4).
+var upload_queue_js_1 = require("./upload-queue.js");
+Object.defineProperty(exports, "KoolbaseUploadQueue", { enumerable: true, get: function () { return upload_queue_js_1.KoolbaseUploadQueue; } });
+Object.defineProperty(exports, "initialUploadQueueState", { enumerable: true, get: function () { return upload_queue_js_1.initialUploadQueueState; } });
 var analytics_js_1 = require("./analytics.js");
 Object.defineProperty(exports, "KoolbaseAnalytics", { enumerable: true, get: function () { return analytics_js_1.KoolbaseAnalytics; } });
 Object.defineProperty(exports, "disabledAnalytics", { enumerable: true, get: function () { return analytics_js_1.disabledAnalytics; } });

package/dist/cjs/react/index.d.ts

@@ -2,3 +2,4 @@ export { createUseCollection, type UseCollectionResult } from './use-collection.
 export { createUseRecord, type UseRecordResult } from './use-record.js';
 export { createUseFiles, type UseFilesResult } from './use-files.js';
 export { createUseFile, type UseFileResult } from './use-file.js';
+export { createUseUploadQueue, type UseUploadQueueResult } from './use-upload-queue.js';

package/dist/cjs/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUseFile = exports.createUseFiles = exports.createUseRecord = exports.createUseCollection = void 0;
+exports.createUseUploadQueue = exports.createUseFile = exports.createUseFiles = exports.createUseRecord = exports.createUseCollection = void 0;
 // React hooks over core's controllers: ONE implementation, exported to apps by
 // @koolbase/react-native (from its root, as always) and @koolbase/js/react.
 // React only -- nothing native, nothing DOM. Deliberately not exported from
@@ -13,3 +13,5 @@ var use_files_js_1 = require("./use-files.js");
 Object.defineProperty(exports, "createUseFiles", { enumerable: true, get: function () { return use_files_js_1.createUseFiles; } });
 var use_file_js_1 = require("./use-file.js");
 Object.defineProperty(exports, "createUseFile", { enumerable: true, get: function () { return use_file_js_1.createUseFile; } });
+var use_upload_queue_js_1 = require("./use-upload-queue.js");
+Object.defineProperty(exports, "createUseUploadQueue", { enumerable: true, get: function () { return use_upload_queue_js_1.createUseUploadQueue; } });

package/dist/cjs/react/use-upload-queue.d.ts

@@ -0,0 +1,18 @@
+import { type KoolbaseUploader, type QueueFile, type UploadQueueState } from '../index.js';
+export interface UseUploadQueueResult extends UploadQueueState {
+    /** Adds files and starts as many as may run; returns their ids. */
+    add: (files: readonly QueueFile[]) => string[];
+    /** Stops one file. */
+    cancel: (id: string) => boolean;
+    /** Stops every file that can still be stopped. */
+    cancelAll: () => void;
+    /** Tries a failed or cancelled file again. */
+    retry: (id: string) => boolean;
+    /** Removes the files that have finished. */
+    clearFinished: () => void;
+    /** Resolves once nothing is running. */
+    whenIdle: () => Promise<void>;
+}
+export declare function createUseUploadQueue(getStorage: () => KoolbaseUploader): (options?: {
+    concurrency?: number;
+}) => UseUploadQueueResult;

package/dist/cjs/react/use-upload-queue.js

@@ -0,0 +1,31 @@
+"use strict";
+// useUploadQueue: several uploads as React state (storage S4).
+//
+// A thin wrapper. Everything about the queue lives in @koolbase/core's
+// KoolbaseUploadQueue, which is tested there; this file only gives a
+// component one queue for its lifetime. Uploads still running when the
+// component goes finish on their own.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUseUploadQueue = createUseUploadQueue;
+const react_1 = require("react");
+const index_js_1 = require("../index.js");
+function createUseUploadQueue(getStorage) {
+    return function useUploadQueue(options = {}) {
+        const ref = (0, react_1.useRef)(null);
+        if (ref.current === null)
+            ref.current = new index_js_1.KoolbaseUploadQueue(getStorage(), options);
+        const queue = ref.current;
+        const subscribe = (0, react_1.useCallback)((onChange) => queue.subscribe(onChange), [queue]);
+        const getSnapshot = (0, react_1.useCallback)(() => queue.getState(), [queue]);
+        const state = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+        return {
+            ...state,
+            add: (0, react_1.useCallback)((files) => queue.add(files), [queue]),
+            cancel: (0, react_1.useCallback)((id) => queue.cancel(id), [queue]),
+            cancelAll: (0, react_1.useCallback)(() => queue.cancelAll(), [queue]),
+            retry: (0, react_1.useCallback)((id) => queue.retry(id), [queue]),
+            clearFinished: (0, react_1.useCallback)(() => queue.clearFinished(), [queue]),
+            whenIdle: (0, react_1.useCallback)(() => queue.whenIdle(), [queue]),
+        };
+    };
+}

package/dist/cjs/upload-queue.d.ts

@@ -0,0 +1,81 @@
+import type { KoolbaseUploadTask } from './storage-transfer.js';
+import type { UploadOptions } from './types.js';
+export type QueuedUploadStatus = 'queued' | 'uploading' | 'verifying' | 'done' | 'failed' | 'cancelled';
+/** One file in the queue. */
+export interface QueuedUpload {
+    /** The queue's own id for it: what cancel and retry take. */
+    readonly id: string;
+    readonly bucket: string;
+    /** Where it goes in the bucket. */
+    readonly path: string;
+    /** What a person calls it: the name given, else the path's last part. */
+    readonly name: string;
+    readonly status: QueuedUploadStatus;
+    /** 0 to 1: the share of its bytes sent; 1 once verifying. */
+    readonly progress: number;
+    /** Why it failed, while status is 'failed'. */
+    readonly error: unknown;
+}
+export interface UploadQueueState {
+    readonly items: readonly QueuedUpload[];
+    /** 0 to 1: the files' average progress, a cancelled one not counted. */
+    readonly progress: number;
+    /** Whether any file is still queued, uploading or verifying. */
+    readonly running: boolean;
+    /** How many have landed, and how many failed. */
+    readonly done: number;
+    readonly failed: number;
+}
+export declare const initialUploadQueueState: UploadQueueState;
+/** A file to add: where it goes, and the bytes as startUpload takes them. */
+export interface QueueFile {
+    bucket: string;
+    path: string;
+    file: UploadOptions['file'];
+    /** Shown for it; the path's last part unless set. */
+    name?: string;
+    overwrite?: boolean;
+    metadata?: UploadOptions['metadata'];
+}
+type QueueTask = Pick<KoolbaseUploadTask, 'onProgress' | 'cancel' | 'result'>;
+/** What the queue needs from storage: startUpload. */
+export type KoolbaseUploader = {
+    startUpload(options: UploadOptions): QueueTask;
+};
+export declare class KoolbaseUploadQueue {
+    readonly concurrency: number;
+    private readonly storage;
+    private entries;
+    private state;
+    private readonly listeners;
+    private idleWaiters;
+    private nextId;
+    private disposed;
+    constructor(storage: KoolbaseUploader, options?: {
+        concurrency?: number;
+    });
+    getState(): UploadQueueState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Adds files to the end of the queue and starts as many as may run. Returns their ids. */
+    add(files: readonly QueueFile[]): string[];
+    /** Stops one file: a queued one never starts; one uploading stops. Returns whether it was stopped. */
+    cancel(id: string): boolean;
+    /** Stops every file that can still be stopped. */
+    cancelAll(): void;
+    /** Tries a failed or cancelled file again, from the start. Returns whether it was queued. */
+    retry(id: string): boolean;
+    /** Removes the files that have finished: landed, failed or cancelled. */
+    clearFinished(): void;
+    /** Resolves once nothing is queued, uploading or verifying. */
+    whenIdle(): Promise<void>;
+    /** Stops reporting. Uploads already running finish on their own. */
+    dispose(): void;
+    private active;
+    private pump;
+    private start;
+    private finish;
+    private patch;
+    private publish;
+}
+export {};

package/dist/cjs/upload-queue.js

@@ -0,0 +1,190 @@
+"use strict";
+// Several uploads in a queue, framework-free (storage S4).
+//
+// Files added together go a few at a time (three unless set), each its own
+// SDK upload task -- so a large one still goes in parts, and a bucket's
+// file lists still reload as each lands. Every file has its own state and
+// progress, and can be cancelled or tried again on its own. No React here,
+// so it is tested in this package; useUploadQueue in @koolbase/react-native
+// and @koolbase/js/react is a thin wrapper. Mirrors the Flutter SDK's
+// KoolbaseUploadQueue.
+//
+//  - queued -> uploading -> verifying -> done, or failed / cancelled
+//  - a queued file cancelled never starts; one uploading stops (once the
+//    server is verifying it, it lands or fails on its own)
+//  - a failed or cancelled file can be tried again: it queues once more,
+//    from the start, under the same path
+//  - a file that fails never stops the others
+//  - progress is the files' average, a cancelled one not counted
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseUploadQueue = exports.initialUploadQueueState = void 0;
+const storage_errors_js_1 = require("./storage-errors.js");
+exports.initialUploadQueueState = Object.freeze({
+    items: Object.freeze([]),
+    progress: 0,
+    running: false,
+    done: 0,
+    failed: 0,
+});
+class KoolbaseUploadQueue {
+    constructor(storage, options = {}) {
+        this.entries = [];
+        this.state = exports.initialUploadQueueState;
+        this.listeners = new Set();
+        this.idleWaiters = [];
+        this.nextId = 0;
+        this.disposed = false;
+        this.storage = storage;
+        this.concurrency = Math.max(1, Math.floor(options.concurrency ?? 3));
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Adds files to the end of the queue and starts as many as may run. Returns their ids. */
+    add(files) {
+        if (this.disposed)
+            return [];
+        const ids = [];
+        for (const source of files) {
+            const id = `u${++this.nextId}`;
+            ids.push(id);
+            this.entries.push({
+                item: { id, bucket: source.bucket, path: source.path, name: source.name || source.path.split('/').pop() || source.path, status: 'queued', progress: 0, error: null },
+                source,
+                task: null,
+                run: 0,
+            });
+        }
+        this.pump();
+        this.publish();
+        return ids;
+    }
+    /** Stops one file: a queued one never starts; one uploading stops. Returns whether it was stopped. */
+    cancel(id) {
+        const e = this.entries.find((x) => x.item.id === id);
+        if (!e)
+            return false;
+        if (e.item.status === 'queued') {
+            this.patch(e, { status: 'cancelled', progress: 0 });
+            this.publish();
+            return true;
+        }
+        if (e.item.status === 'uploading')
+            return e.task?.cancel() ?? false;
+        return false;
+    }
+    /** Stops every file that can still be stopped. */
+    cancelAll() {
+        for (const e of [...this.entries])
+            this.cancel(e.item.id);
+    }
+    /** Tries a failed or cancelled file again, from the start. Returns whether it was queued. */
+    retry(id) {
+        const e = this.entries.find((x) => x.item.id === id);
+        if (!e || (e.item.status !== 'failed' && e.item.status !== 'cancelled') || this.disposed)
+            return false;
+        e.task = null;
+        this.patch(e, { status: 'queued', progress: 0, error: null });
+        this.pump();
+        this.publish();
+        return true;
+    }
+    /** Removes the files that have finished: landed, failed or cancelled. */
+    clearFinished() {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.item.status === 'queued' || e.item.status === 'uploading' || e.item.status === 'verifying');
+        if (this.entries.length !== before)
+            this.publish();
+    }
+    /** Resolves once nothing is queued, uploading or verifying. */
+    whenIdle() {
+        if (!this.state.running)
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.push(resolve));
+    }
+    /** Stops reporting. Uploads already running finish on their own. */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    active() {
+        return this.entries.filter((e) => e.item.status === 'uploading' || e.item.status === 'verifying').length;
+    }
+    pump() {
+        if (this.disposed)
+            return;
+        let free = this.concurrency - this.active();
+        for (const e of this.entries) {
+            if (free <= 0)
+                break;
+            if (e.item.status !== 'queued')
+                continue;
+            free--;
+            this.start(e);
+        }
+    }
+    start(e) {
+        const run = ++e.run;
+        this.patch(e, { status: 'uploading', progress: 0, error: null });
+        let task;
+        try {
+            task = this.storage.startUpload({ bucket: e.source.bucket, path: e.source.path, file: e.source.file, overwrite: e.source.overwrite, metadata: e.source.metadata });
+        }
+        catch (err) {
+            this.finish(e, run, 'failed', err);
+            return;
+        }
+        e.task = task;
+        task.onProgress((p) => {
+            if (e.run !== run || e.item.status === 'cancelled' || p.isDone)
+                return;
+            const status = p.state === 'verifying' ? 'verifying' : 'uploading';
+            if (status === e.item.status && p.fraction === e.item.progress)
+                return;
+            this.patch(e, { status, progress: p.fraction });
+            this.publish();
+        });
+        task.result.then(() => this.finish(e, run, 'done', null), (err) => this.finish(e, run, err instanceof storage_errors_js_1.KoolbaseUploadCancelledError ? 'cancelled' : 'failed', err));
+    }
+    finish(e, run, status, err) {
+        if (e.run !== run)
+            return;
+        e.task = null;
+        this.patch(e, { status, progress: status === 'done' ? 1 : status === 'cancelled' ? 0 : e.item.progress, error: status === 'failed' ? err : null });
+        this.pump();
+        this.publish();
+    }
+    patch(e, change) {
+        e.item = Object.freeze({ ...e.item, ...change });
+    }
+    publish() {
+        const items = Object.freeze(this.entries.map((e) => e.item));
+        const counted = items.filter((i) => i.status !== 'cancelled');
+        const running = items.some((i) => i.status === 'queued' || i.status === 'uploading' || i.status === 'verifying');
+        this.state = Object.freeze({
+            items,
+            progress: counted.length ? counted.reduce((s, i) => s + i.progress, 0) / counted.length : 0,
+            running,
+            done: items.filter((i) => i.status === 'done').length,
+            failed: items.filter((i) => i.status === 'failed').length,
+        });
+        if (!running && this.idleWaiters.length) {
+            const waiters = this.idleWaiters;
+            this.idleWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+        if (this.disposed)
+            return;
+        for (const l of [...this.listeners])
+            l();
+    }
+}
+exports.KoolbaseUploadQueue = KoolbaseUploadQueue;

package/dist/esm/index.d.ts

@@ -27,6 +27,8 @@ export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './fil
 export type { FilesQuery, FilesState, FilesStatus } from './files-controller.js';
 export { KoolbaseFileController, initialFileState } from './file-controller.js';
 export type { FileState, FileStatus } from './file-controller.js';
+export { KoolbaseUploadQueue, initialUploadQueueState } from './upload-queue.js';
+export type { KoolbaseUploader, QueuedUpload, QueuedUploadStatus, QueueFile, UploadQueueState } from './upload-queue.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';

package/dist/esm/index.js

@@ -27,6 +27,8 @@ export { KoolbaseUploadTask } from './storage-transfer.js';
 export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './files-controller.js';
 // One file's details as state (storage S4).
 export { KoolbaseFileController, initialFileState } from './file-controller.js';
+// Several uploads in a queue (storage S4).
+export { KoolbaseUploadQueue, initialUploadQueueState } from './upload-queue.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';

package/dist/esm/react/index.d.ts

@@ -2,3 +2,4 @@ export { createUseCollection, type UseCollectionResult } from './use-collection.
 export { createUseRecord, type UseRecordResult } from './use-record.js';
 export { createUseFiles, type UseFilesResult } from './use-files.js';
 export { createUseFile, type UseFileResult } from './use-file.js';
+export { createUseUploadQueue, type UseUploadQueueResult } from './use-upload-queue.js';

package/dist/esm/react/index.js

@@ -6,3 +6,4 @@ export { createUseCollection } from './use-collection.js';
 export { createUseRecord } from './use-record.js';
 export { createUseFiles } from './use-files.js';
 export { createUseFile } from './use-file.js';
+export { createUseUploadQueue } from './use-upload-queue.js';

package/dist/esm/react/use-upload-queue.d.ts

@@ -0,0 +1,18 @@
+import { type KoolbaseUploader, type QueueFile, type UploadQueueState } from '../index.js';
+export interface UseUploadQueueResult extends UploadQueueState {
+    /** Adds files and starts as many as may run; returns their ids. */
+    add: (files: readonly QueueFile[]) => string[];
+    /** Stops one file. */
+    cancel: (id: string) => boolean;
+    /** Stops every file that can still be stopped. */
+    cancelAll: () => void;
+    /** Tries a failed or cancelled file again. */
+    retry: (id: string) => boolean;
+    /** Removes the files that have finished. */
+    clearFinished: () => void;
+    /** Resolves once nothing is running. */
+    whenIdle: () => Promise<void>;
+}
+export declare function createUseUploadQueue(getStorage: () => KoolbaseUploader): (options?: {
+    concurrency?: number;
+}) => UseUploadQueueResult;

package/dist/esm/react/use-upload-queue.js

@@ -0,0 +1,28 @@
+// useUploadQueue: several uploads as React state (storage S4).
+//
+// A thin wrapper. Everything about the queue lives in @koolbase/core's
+// KoolbaseUploadQueue, which is tested there; this file only gives a
+// component one queue for its lifetime. Uploads still running when the
+// component goes finish on their own.
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+import { KoolbaseUploadQueue } from '../index.js';
+export function createUseUploadQueue(getStorage) {
+    return function useUploadQueue(options = {}) {
+        const ref = useRef(null);
+        if (ref.current === null)
+            ref.current = new KoolbaseUploadQueue(getStorage(), options);
+        const queue = ref.current;
+        const subscribe = useCallback((onChange) => queue.subscribe(onChange), [queue]);
+        const getSnapshot = useCallback(() => queue.getState(), [queue]);
+        const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+        return {
+            ...state,
+            add: useCallback((files) => queue.add(files), [queue]),
+            cancel: useCallback((id) => queue.cancel(id), [queue]),
+            cancelAll: useCallback(() => queue.cancelAll(), [queue]),
+            retry: useCallback((id) => queue.retry(id), [queue]),
+            clearFinished: useCallback(() => queue.clearFinished(), [queue]),
+            whenIdle: useCallback(() => queue.whenIdle(), [queue]),
+        };
+    };
+}

package/dist/esm/upload-queue.d.ts

@@ -0,0 +1,81 @@
+import type { KoolbaseUploadTask } from './storage-transfer.js';
+import type { UploadOptions } from './types.js';
+export type QueuedUploadStatus = 'queued' | 'uploading' | 'verifying' | 'done' | 'failed' | 'cancelled';
+/** One file in the queue. */
+export interface QueuedUpload {
+    /** The queue's own id for it: what cancel and retry take. */
+    readonly id: string;
+    readonly bucket: string;
+    /** Where it goes in the bucket. */
+    readonly path: string;
+    /** What a person calls it: the name given, else the path's last part. */
+    readonly name: string;
+    readonly status: QueuedUploadStatus;
+    /** 0 to 1: the share of its bytes sent; 1 once verifying. */
+    readonly progress: number;
+    /** Why it failed, while status is 'failed'. */
+    readonly error: unknown;
+}
+export interface UploadQueueState {
+    readonly items: readonly QueuedUpload[];
+    /** 0 to 1: the files' average progress, a cancelled one not counted. */
+    readonly progress: number;
+    /** Whether any file is still queued, uploading or verifying. */
+    readonly running: boolean;
+    /** How many have landed, and how many failed. */
+    readonly done: number;
+    readonly failed: number;
+}
+export declare const initialUploadQueueState: UploadQueueState;
+/** A file to add: where it goes, and the bytes as startUpload takes them. */
+export interface QueueFile {
+    bucket: string;
+    path: string;
+    file: UploadOptions['file'];
+    /** Shown for it; the path's last part unless set. */
+    name?: string;
+    overwrite?: boolean;
+    metadata?: UploadOptions['metadata'];
+}
+type QueueTask = Pick<KoolbaseUploadTask, 'onProgress' | 'cancel' | 'result'>;
+/** What the queue needs from storage: startUpload. */
+export type KoolbaseUploader = {
+    startUpload(options: UploadOptions): QueueTask;
+};
+export declare class KoolbaseUploadQueue {
+    readonly concurrency: number;
+    private readonly storage;
+    private entries;
+    private state;
+    private readonly listeners;
+    private idleWaiters;
+    private nextId;
+    private disposed;
+    constructor(storage: KoolbaseUploader, options?: {
+        concurrency?: number;
+    });
+    getState(): UploadQueueState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Adds files to the end of the queue and starts as many as may run. Returns their ids. */
+    add(files: readonly QueueFile[]): string[];
+    /** Stops one file: a queued one never starts; one uploading stops. Returns whether it was stopped. */
+    cancel(id: string): boolean;
+    /** Stops every file that can still be stopped. */
+    cancelAll(): void;
+    /** Tries a failed or cancelled file again, from the start. Returns whether it was queued. */
+    retry(id: string): boolean;
+    /** Removes the files that have finished: landed, failed or cancelled. */
+    clearFinished(): void;
+    /** Resolves once nothing is queued, uploading or verifying. */
+    whenIdle(): Promise<void>;
+    /** Stops reporting. Uploads already running finish on their own. */
+    dispose(): void;
+    private active;
+    private pump;
+    private start;
+    private finish;
+    private patch;
+    private publish;
+}
+export {};

package/dist/esm/upload-queue.js

@@ -0,0 +1,186 @@
+// Several uploads in a queue, framework-free (storage S4).
+//
+// Files added together go a few at a time (three unless set), each its own
+// SDK upload task -- so a large one still goes in parts, and a bucket's
+// file lists still reload as each lands. Every file has its own state and
+// progress, and can be cancelled or tried again on its own. No React here,
+// so it is tested in this package; useUploadQueue in @koolbase/react-native
+// and @koolbase/js/react is a thin wrapper. Mirrors the Flutter SDK's
+// KoolbaseUploadQueue.
+//
+//  - queued -> uploading -> verifying -> done, or failed / cancelled
+//  - a queued file cancelled never starts; one uploading stops (once the
+//    server is verifying it, it lands or fails on its own)
+//  - a failed or cancelled file can be tried again: it queues once more,
+//    from the start, under the same path
+//  - a file that fails never stops the others
+//  - progress is the files' average, a cancelled one not counted
+import { KoolbaseUploadCancelledError } from './storage-errors.js';
+export const initialUploadQueueState = Object.freeze({
+    items: Object.freeze([]),
+    progress: 0,
+    running: false,
+    done: 0,
+    failed: 0,
+});
+export class KoolbaseUploadQueue {
+    constructor(storage, options = {}) {
+        this.entries = [];
+        this.state = initialUploadQueueState;
+        this.listeners = new Set();
+        this.idleWaiters = [];
+        this.nextId = 0;
+        this.disposed = false;
+        this.storage = storage;
+        this.concurrency = Math.max(1, Math.floor(options.concurrency ?? 3));
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Adds files to the end of the queue and starts as many as may run. Returns their ids. */
+    add(files) {
+        if (this.disposed)
+            return [];
+        const ids = [];
+        for (const source of files) {
+            const id = `u${++this.nextId}`;
+            ids.push(id);
+            this.entries.push({
+                item: { id, bucket: source.bucket, path: source.path, name: source.name || source.path.split('/').pop() || source.path, status: 'queued', progress: 0, error: null },
+                source,
+                task: null,
+                run: 0,
+            });
+        }
+        this.pump();
+        this.publish();
+        return ids;
+    }
+    /** Stops one file: a queued one never starts; one uploading stops. Returns whether it was stopped. */
+    cancel(id) {
+        const e = this.entries.find((x) => x.item.id === id);
+        if (!e)
+            return false;
+        if (e.item.status === 'queued') {
+            this.patch(e, { status: 'cancelled', progress: 0 });
+            this.publish();
+            return true;
+        }
+        if (e.item.status === 'uploading')
+            return e.task?.cancel() ?? false;
+        return false;
+    }
+    /** Stops every file that can still be stopped. */
+    cancelAll() {
+        for (const e of [...this.entries])
+            this.cancel(e.item.id);
+    }
+    /** Tries a failed or cancelled file again, from the start. Returns whether it was queued. */
+    retry(id) {
+        const e = this.entries.find((x) => x.item.id === id);
+        if (!e || (e.item.status !== 'failed' && e.item.status !== 'cancelled') || this.disposed)
+            return false;
+        e.task = null;
+        this.patch(e, { status: 'queued', progress: 0, error: null });
+        this.pump();
+        this.publish();
+        return true;
+    }
+    /** Removes the files that have finished: landed, failed or cancelled. */
+    clearFinished() {
+        const before = this.entries.length;
+        this.entries = this.entries.filter((e) => e.item.status === 'queued' || e.item.status === 'uploading' || e.item.status === 'verifying');
+        if (this.entries.length !== before)
+            this.publish();
+    }
+    /** Resolves once nothing is queued, uploading or verifying. */
+    whenIdle() {
+        if (!this.state.running)
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.push(resolve));
+    }
+    /** Stops reporting. Uploads already running finish on their own. */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    active() {
+        return this.entries.filter((e) => e.item.status === 'uploading' || e.item.status === 'verifying').length;
+    }
+    pump() {
+        if (this.disposed)
+            return;
+        let free = this.concurrency - this.active();
+        for (const e of this.entries) {
+            if (free <= 0)
+                break;
+            if (e.item.status !== 'queued')
+                continue;
+            free--;
+            this.start(e);
+        }
+    }
+    start(e) {
+        const run = ++e.run;
+        this.patch(e, { status: 'uploading', progress: 0, error: null });
+        let task;
+        try {
+            task = this.storage.startUpload({ bucket: e.source.bucket, path: e.source.path, file: e.source.file, overwrite: e.source.overwrite, metadata: e.source.metadata });
+        }
+        catch (err) {
+            this.finish(e, run, 'failed', err);
+            return;
+        }
+        e.task = task;
+        task.onProgress((p) => {
+            if (e.run !== run || e.item.status === 'cancelled' || p.isDone)
+                return;
+            const status = p.state === 'verifying' ? 'verifying' : 'uploading';
+            if (status === e.item.status && p.fraction === e.item.progress)
+                return;
+            this.patch(e, { status, progress: p.fraction });
+            this.publish();
+        });
+        task.result.then(() => this.finish(e, run, 'done', null), (err) => this.finish(e, run, err instanceof KoolbaseUploadCancelledError ? 'cancelled' : 'failed', err));
+    }
+    finish(e, run, status, err) {
+        if (e.run !== run)
+            return;
+        e.task = null;
+        this.patch(e, { status, progress: status === 'done' ? 1 : status === 'cancelled' ? 0 : e.item.progress, error: status === 'failed' ? err : null });
+        this.pump();
+        this.publish();
+    }
+    patch(e, change) {
+        e.item = Object.freeze({ ...e.item, ...change });
+    }
+    publish() {
+        const items = Object.freeze(this.entries.map((e) => e.item));
+        const counted = items.filter((i) => i.status !== 'cancelled');
+        const running = items.some((i) => i.status === 'queued' || i.status === 'uploading' || i.status === 'verifying');
+        this.state = Object.freeze({
+            items,
+            progress: counted.length ? counted.reduce((s, i) => s + i.progress, 0) / counted.length : 0,
+            running,
+            done: items.filter((i) => i.status === 'done').length,
+            failed: items.filter((i) => i.status === 'failed').length,
+        });
+        if (!running && this.idleWaiters.length) {
+            const waiters = this.idleWaiters;
+            this.idleWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+        if (this.disposed)
+            return;
+        for (const l of [...this.listeners])
+            l();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.20.0",
+  "version": "12.21.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",