@koolbase/core 12.19.0 → 12.21.0

package/dist/cjs/file-controller.d.ts

@@ -0,0 +1,39 @@
+import type { KoolbaseFileInfo } from './storage-files.js';
+export type FileStatus = 'loading' | 'loaded' | 'notFound' | 'error';
+export interface FileState {
+    readonly status: FileStatus;
+    /** The file's details, while status is 'loaded'. */
+    readonly file: KoolbaseFileInfo | null;
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+}
+export declare const initialFileState: FileState;
+type FileReader = {
+    getFileInfo(bucket: string, path: string): Promise<KoolbaseFileInfo>;
+};
+export declare class KoolbaseFileController {
+    readonly bucket: string;
+    readonly path: string;
+    private readonly storage;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    private unregister;
+    constructor(storage: FileReader, bucket: string, path: string);
+    getState(): FileState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** Read it again. The file stays shown while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose(): void;
+    private run;
+    private isStale;
+    private set;
+}
+export {};

package/dist/cjs/file-controller.js

@@ -0,0 +1,115 @@
+"use strict";
+// One file's details, by path, framework-free (storage S4).
+//
+// The data half of a file detail screen: loading, loaded, not found or
+// error, and refresh. No React here, so it is tested in this package; useFile
+// in @koolbase/react-native and @koolbase/js/react is a thin wrapper.
+// Mirrors the Flutter SDK's KoolbaseFileController, with the record view's
+// rules:
+//
+//  - an empty path is not found, with no request
+//  - not found is not an error: the API answers a file you may not view as
+//    not found too, so a detail screen says "not available"
+//  - stale beats blank: a failed refresh keeps the file shown
+//  - a change made through this SDK in the bucket (an upload, a delete, a
+//    move, a metadata change, a restore) reads it again silently: deleted or
+//    moved away, the file is not found; replaced, it shows its new size
+//  - a result a later load superseded, or one landing after dispose(), is
+//    dropped
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseFileController = exports.initialFileState = void 0;
+const files_refresh_js_1 = require("./files-refresh.js");
+const storage_errors_js_1 = require("./storage-errors.js");
+exports.initialFileState = Object.freeze({
+    status: 'loading',
+    file: null,
+    error: null,
+    refreshing: false,
+});
+/** Whether [e] says there is no such file (or none this caller may view). */
+function isNotFound(e) {
+    return e instanceof storage_errors_js_1.KoolbaseStorageNotFoundError || e?.code === 'not_found';
+}
+class KoolbaseFileController {
+    constructor(storage, bucket, path) {
+        this.state = exports.initialFileState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.unregister = null;
+        this.storage = storage;
+        this.bucket = bucket;
+        this.path = path;
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        if (this.disposed)
+            return () => { };
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** The first load. Call once; refresh() for later loads. */
+    async load() {
+        if (this.disposed)
+            return;
+        if (this.path)
+            this.unregister ?? (this.unregister = (0, files_refresh_js_1.registerFilesRefresher)(this.bucket, () => this.run()));
+        await this.run();
+    }
+    /** Read it again. The file stays shown while it runs, and stays if it fails. */
+    async refresh() {
+        if (this.disposed)
+            return;
+        this.set({ refreshing: true });
+        await this.run();
+    }
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose() {
+        this.disposed = true;
+        this.unregister?.();
+        this.unregister = null;
+        this.listeners.clear();
+    }
+    async run() {
+        if (this.disposed)
+            return;
+        const gen = ++this.generation;
+        if (!this.path) {
+            this.set({ status: 'notFound', file: null, error: null, refreshing: false });
+            return;
+        }
+        try {
+            const file = await this.storage.getFileInfo(this.bucket, this.path);
+            if (this.isStale(gen))
+                return;
+            this.set({ status: 'loaded', file, error: null, refreshing: false });
+        }
+        catch (e) {
+            if (this.isStale(gen))
+                return;
+            if (isNotFound(e))
+                this.set({ status: 'notFound', file: null, error: null, refreshing: false });
+            // Only a first load with nothing to show is the error state.
+            else if (this.state.file === null)
+                this.set({ status: 'error', file: null, error: e, refreshing: false });
+            else
+                this.set({ refreshing: false });
+        }
+    }
+    isStale(gen) {
+        return this.disposed || gen !== this.generation;
+    }
+    set(change) {
+        if (this.disposed)
+            return;
+        this.state = Object.freeze({ ...this.state, ...change });
+        for (const l of [...this.listeners])
+            l();
+    }
+}
+exports.KoolbaseFileController = KoolbaseFileController;

package/dist/cjs/index.d.ts

@@ -25,6 +25,10 @@ export type { KoolbaseUploadProgress, KoolbaseUploadState } from './storage-tran
 export type { KoolbaseFileInfo, KoolbaseFilePage, KoolbaseFileSort, ListFilesOptions } from './storage-files.js';
 export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './files-controller.js';
 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.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);
@@ -58,6 +58,14 @@ var files_controller_js_1 = require("./files-controller.js");
 Object.defineProperty(exports, "KoolbaseFilesController", { enumerable: true, get: function () { return files_controller_js_1.KoolbaseFilesController; } });
 Object.defineProperty(exports, "initialFilesState", { enumerable: true, get: function () { return files_controller_js_1.initialFilesState; } });
 Object.defineProperty(exports, "filesQueryKey", { enumerable: true, get: function () { return files_controller_js_1.filesQueryKey; } });
+// One file's details as state (storage S4).
+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

@@ -1,3 +1,5 @@
 export { createUseCollection, type UseCollectionResult } from './use-collection.js';
 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.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
@@ -11,3 +11,7 @@ var use_record_js_1 = require("./use-record.js");
 Object.defineProperty(exports, "createUseRecord", { enumerable: true, get: function () { return use_record_js_1.createUseRecord; } });
 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-file.d.ts

@@ -0,0 +1,6 @@
+import { type FileState, type KoolbaseStorage } from '../index.js';
+export interface UseFileResult extends FileState {
+    /** Read it again. The file stays shown while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+}
+export declare function createUseFile(getStorage: () => Pick<KoolbaseStorage, 'getFileInfo'>): (bucket: string, path: string | null | undefined) => UseFileResult;

package/dist/cjs/react/use-file.js

@@ -0,0 +1,35 @@
+"use strict";
+// useFile: one file's details as React state (storage S4).
+//
+// A thin wrapper. Everything about getting the file right lives in
+// @koolbase/core's KoolbaseFileController, which is tested there; this file
+// only ties one controller's lifetime to a component's.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUseFile = createUseFile;
+const react_1 = require("react");
+const index_js_1 = require("../index.js");
+const noop = () => { };
+const done = () => Promise.resolve();
+function createUseFile(getStorage) {
+    return function useFile(bucket, path) {
+        const p = path ?? '';
+        const key = JSON.stringify([bucket, p]);
+        const [current, setCurrent] = (0, react_1.useState)(null);
+        (0, react_1.useEffect)(() => {
+            // Created here, not during render, so React strict mode's second run
+            // never keeps a disposed controller.
+            const controller = new index_js_1.KoolbaseFileController(getStorage(), bucket, p);
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+        }, [key]);
+        // A controller from the previous file reads as a fresh load, never as
+        // the previous file.
+        const controller = current?.key === key ? current.controller : null;
+        const subscribe = (0, react_1.useCallback)((onChange) => (controller ? controller.subscribe(onChange) : noop), [controller]);
+        const getSnapshot = (0, react_1.useCallback)(() => (controller ? controller.getState() : index_js_1.initialFileState), [controller]);
+        const state = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+        const refresh = (0, react_1.useCallback)(() => (controller ? controller.refresh() : done()), [controller]);
+        return { ...state, refresh };
+    };
+}

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/file-controller.d.ts

@@ -0,0 +1,39 @@
+import type { KoolbaseFileInfo } from './storage-files.js';
+export type FileStatus = 'loading' | 'loaded' | 'notFound' | 'error';
+export interface FileState {
+    readonly status: FileStatus;
+    /** The file's details, while status is 'loaded'. */
+    readonly file: KoolbaseFileInfo | null;
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+}
+export declare const initialFileState: FileState;
+type FileReader = {
+    getFileInfo(bucket: string, path: string): Promise<KoolbaseFileInfo>;
+};
+export declare class KoolbaseFileController {
+    readonly bucket: string;
+    readonly path: string;
+    private readonly storage;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    private unregister;
+    constructor(storage: FileReader, bucket: string, path: string);
+    getState(): FileState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** Read it again. The file stays shown while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose(): void;
+    private run;
+    private isStale;
+    private set;
+}
+export {};

package/dist/esm/file-controller.js

@@ -0,0 +1,111 @@
+// One file's details, by path, framework-free (storage S4).
+//
+// The data half of a file detail screen: loading, loaded, not found or
+// error, and refresh. No React here, so it is tested in this package; useFile
+// in @koolbase/react-native and @koolbase/js/react is a thin wrapper.
+// Mirrors the Flutter SDK's KoolbaseFileController, with the record view's
+// rules:
+//
+//  - an empty path is not found, with no request
+//  - not found is not an error: the API answers a file you may not view as
+//    not found too, so a detail screen says "not available"
+//  - stale beats blank: a failed refresh keeps the file shown
+//  - a change made through this SDK in the bucket (an upload, a delete, a
+//    move, a metadata change, a restore) reads it again silently: deleted or
+//    moved away, the file is not found; replaced, it shows its new size
+//  - a result a later load superseded, or one landing after dispose(), is
+//    dropped
+import { registerFilesRefresher } from './files-refresh.js';
+import { KoolbaseStorageNotFoundError } from './storage-errors.js';
+export const initialFileState = Object.freeze({
+    status: 'loading',
+    file: null,
+    error: null,
+    refreshing: false,
+});
+/** Whether [e] says there is no such file (or none this caller may view). */
+function isNotFound(e) {
+    return e instanceof KoolbaseStorageNotFoundError || e?.code === 'not_found';
+}
+export class KoolbaseFileController {
+    constructor(storage, bucket, path) {
+        this.state = initialFileState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.unregister = null;
+        this.storage = storage;
+        this.bucket = bucket;
+        this.path = path;
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        if (this.disposed)
+            return () => { };
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** The first load. Call once; refresh() for later loads. */
+    async load() {
+        if (this.disposed)
+            return;
+        if (this.path)
+            this.unregister ?? (this.unregister = registerFilesRefresher(this.bucket, () => this.run()));
+        await this.run();
+    }
+    /** Read it again. The file stays shown while it runs, and stays if it fails. */
+    async refresh() {
+        if (this.disposed)
+            return;
+        this.set({ refreshing: true });
+        await this.run();
+    }
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose() {
+        this.disposed = true;
+        this.unregister?.();
+        this.unregister = null;
+        this.listeners.clear();
+    }
+    async run() {
+        if (this.disposed)
+            return;
+        const gen = ++this.generation;
+        if (!this.path) {
+            this.set({ status: 'notFound', file: null, error: null, refreshing: false });
+            return;
+        }
+        try {
+            const file = await this.storage.getFileInfo(this.bucket, this.path);
+            if (this.isStale(gen))
+                return;
+            this.set({ status: 'loaded', file, error: null, refreshing: false });
+        }
+        catch (e) {
+            if (this.isStale(gen))
+                return;
+            if (isNotFound(e))
+                this.set({ status: 'notFound', file: null, error: null, refreshing: false });
+            // Only a first load with nothing to show is the error state.
+            else if (this.state.file === null)
+                this.set({ status: 'error', file: null, error: e, refreshing: false });
+            else
+                this.set({ refreshing: false });
+        }
+    }
+    isStale(gen) {
+        return this.disposed || gen !== this.generation;
+    }
+    set(change) {
+        if (this.disposed)
+            return;
+        this.state = Object.freeze({ ...this.state, ...change });
+        for (const l of [...this.listeners])
+            l();
+    }
+}

package/dist/esm/index.d.ts

@@ -25,6 +25,10 @@ export type { KoolbaseUploadProgress, KoolbaseUploadState } from './storage-tran
 export type { KoolbaseFileInfo, KoolbaseFilePage, KoolbaseFileSort, ListFilesOptions } from './storage-files.js';
 export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './files-controller.js';
 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

@@ -25,6 +25,10 @@ export { KoolbaseStorage } from './storage.js';
 export { KoolbaseUploadTask } from './storage-transfer.js';
 // A bucket's files as list state (storage S4).
 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

@@ -1,3 +1,5 @@
 export { createUseCollection, type UseCollectionResult } from './use-collection.js';
 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

@@ -5,3 +5,5 @@
 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-file.d.ts

@@ -0,0 +1,6 @@
+import { type FileState, type KoolbaseStorage } from '../index.js';
+export interface UseFileResult extends FileState {
+    /** Read it again. The file stays shown while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+}
+export declare function createUseFile(getStorage: () => Pick<KoolbaseStorage, 'getFileInfo'>): (bucket: string, path: string | null | undefined) => UseFileResult;

package/dist/esm/react/use-file.js

@@ -0,0 +1,32 @@
+// useFile: one file's details as React state (storage S4).
+//
+// A thin wrapper. Everything about getting the file right lives in
+// @koolbase/core's KoolbaseFileController, which is tested there; this file
+// only ties one controller's lifetime to a component's.
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { KoolbaseFileController, initialFileState } from '../index.js';
+const noop = () => { };
+const done = () => Promise.resolve();
+export function createUseFile(getStorage) {
+    return function useFile(bucket, path) {
+        const p = path ?? '';
+        const key = JSON.stringify([bucket, p]);
+        const [current, setCurrent] = useState(null);
+        useEffect(() => {
+            // Created here, not during render, so React strict mode's second run
+            // never keeps a disposed controller.
+            const controller = new KoolbaseFileController(getStorage(), bucket, p);
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+        }, [key]);
+        // A controller from the previous file reads as a fresh load, never as
+        // the previous file.
+        const controller = current?.key === key ? current.controller : null;
+        const subscribe = useCallback((onChange) => (controller ? controller.subscribe(onChange) : noop), [controller]);
+        const getSnapshot = useCallback(() => (controller ? controller.getState() : initialFileState), [controller]);
+        const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+        const refresh = useCallback(() => (controller ? controller.refresh() : done()), [controller]);
+        return { ...state, refresh };
+    };
+}

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.19.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",