@koolbase/core 12.17.0 → 12.19.0

package/dist/cjs/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 {};

package/dist/cjs/files-controller.js

@@ -0,0 +1,160 @@
+"use strict";
+// A bucket's files read as a list, framework-free (storage S4).
+//
+// The data half of a file gallery: loading, loaded or error, refresh, and
+// the next page by cursor. No React here, so it is tested in this package;
+// useFiles in @koolbase/react-native and @koolbase/js/react is a thin
+// wrapper. Mirrors the Flutter SDK's KoolbaseFilesController.
+//
+//  - only a first load with nothing to show is the error state; a failed
+//    refresh or loadMore keeps what is shown (stale beats blank)
+//  - loadMore appends the next page while there is one; a file already
+//    shown is never shown twice (matched by path)
+//  - an upload, delete, move, copy, metadata change or restore made through
+//    this SDK in the bucket reloads page one silently (files-refresh.ts)
+//  - every fetch belongs to a generation: a result from a fetch a later
+//    refresh superseded, or one landing after dispose(), is dropped
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseFilesController = exports.initialFilesState = void 0;
+exports.filesQueryKey = filesQueryKey;
+const files_refresh_js_1 = require("./files-refresh.js");
+exports.initialFilesState = Object.freeze({
+    status: 'loading',
+    files: Object.freeze([]),
+    error: null,
+    refreshing: false,
+    loadingMore: false,
+    hasMore: true,
+});
+/** One string per distinct listing. */
+function filesQueryKey(bucket, query = {}) {
+    return JSON.stringify([bucket, query.prefix ?? '', query.sort ?? 'path', query.descending === true, query.limit ?? null]);
+}
+/** Page one, then the later pages without any file already shown. */
+function mergeByPath(first, rest) {
+    const seen = new Set(first.map((f) => f.path));
+    const out = [...first];
+    for (const f of rest) {
+        if (seen.has(f.path))
+            continue;
+        seen.add(f.path);
+        out.push(f);
+    }
+    return out;
+}
+class KoolbaseFilesController {
+    constructor(storage, bucket, query = {}) {
+        this.state = exports.initialFilesState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.pageOne = [];
+        this.laterPages = [];
+        this.cursor = null;
+        this.unregister = null;
+        this.storage = storage;
+        this.bucket = bucket;
+        this.spec = query;
+    }
+    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;
+        this.unregister ?? (this.unregister = (0, files_refresh_js_1.registerFilesRefresher)(this.bucket, () => this.firstPage()));
+        await this.firstPage();
+    }
+    /** Page one again. What is shown stays while it runs, and stays if it fails. */
+    async refresh() {
+        if (this.disposed)
+            return;
+        this.set({ refreshing: true });
+        await this.firstPage();
+    }
+    /** The next page, appended. Does nothing unless loaded with a page to come. */
+    async loadMore() {
+        const s = this.state;
+        if (this.disposed || s.loadingMore || !s.hasMore || s.status !== 'loaded' || this.cursor === null)
+            return;
+        const gen = this.generation;
+        this.set({ loadingMore: true });
+        try {
+            const page = await this.storage.listFiles(this.options(this.cursor));
+            if (this.isStale(gen))
+                return;
+            this.laterPages = [...this.laterPages, ...page.files];
+            this.cursor = page.nextCursor;
+            this.publish({});
+        }
+        catch {
+            // Keep what is shown; the caller can try again.
+        }
+        finally {
+            if (!this.isStale(gen))
+                this.set({ loadingMore: false });
+        }
+    }
+    /** 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 firstPage() {
+        const gen = ++this.generation;
+        if (this.state.loadingMore)
+            this.set({ loadingMore: false });
+        try {
+            const page = await this.storage.listFiles(this.options(undefined));
+            if (!this.isStale(gen)) {
+                this.pageOne = page.files;
+                this.laterPages = [];
+                this.cursor = page.nextCursor;
+                this.publish({ status: 'loaded', error: null, refreshing: false });
+            }
+        }
+        catch (error) {
+            // Only a first load with nothing to show is the error state. Whichever
+            // fetch is newest ends a refresh, a silent one included.
+            if (!this.isStale(gen)) {
+                this.set(this.state.files.length === 0 ? { status: 'error', error, refreshing: false } : { refreshing: false });
+            }
+        }
+    }
+    publish(patch) {
+        this.set({ ...patch, files: mergeByPath(this.pageOne, this.laterPages), hasMore: this.cursor !== null });
+    }
+    options(cursor) {
+        return {
+            bucket: this.bucket,
+            ...(this.spec.prefix ? { prefix: this.spec.prefix } : {}),
+            ...(this.spec.limit != null ? { limit: this.spec.limit } : {}),
+            ...(this.spec.sort ? { sort: this.spec.sort } : {}),
+            ...(this.spec.descending ? { descending: true } : {}),
+            ...(cursor ? { cursor } : {}),
+        };
+    }
+    isStale(gen) {
+        return this.disposed || gen !== this.generation;
+    }
+    set(patch) {
+        if (this.disposed)
+            return;
+        this.state = Object.freeze({ ...this.state, ...patch });
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+exports.KoolbaseFilesController = KoolbaseFilesController;

package/dist/cjs/files-refresh.d.ts

@@ -0,0 +1,9 @@
+/** Registers one file list's reload; returns the unregister. */
+export declare function registerFilesRefresher(bucket: string, refresh: () => Promise<void>): () => void;
+/**
+ * Reloads every file list on [buckets]. One after another; a failure in one
+ * never stops the others, and never reaches the change that caused it.
+ */
+export declare function refreshBucketFiles(...buckets: string[]): Promise<void>;
+/** Tests only. */
+export declare function clearFilesRefreshers(): void;

package/dist/cjs/files-refresh.js

@@ -0,0 +1,39 @@
+"use strict";
+// File lists reloaded after a change made through this SDK (storage S4): an
+// upload, a delete, a move or copy, a metadata change, a restore. Keyed by
+// bucket; each list reloads ITSELF, with its own prefix and order.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFilesRefresher = registerFilesRefresher;
+exports.refreshBucketFiles = refreshBucketFiles;
+exports.clearFilesRefreshers = clearFilesRefreshers;
+const refreshers = new Map();
+let next = 0;
+/** Registers one file list's reload; returns the unregister. */
+function registerFilesRefresher(bucket, refresh) {
+    const key = `${bucket}\u0000${++next}`;
+    refreshers.set(key, refresh);
+    return () => {
+        refreshers.delete(key);
+    };
+}
+/**
+ * Reloads every file list on [buckets]. One after another; a failure in one
+ * never stops the others, and never reaches the change that caused it.
+ */
+async function refreshBucketFiles(...buckets) {
+    const prefixes = buckets.map((b) => `${b}\u0000`);
+    const due = [...refreshers.entries()].filter(([k]) => prefixes.some((p) => k.startsWith(p))).map(([, f]) => f);
+    for (const refresh of due) {
+        try {
+            await refresh();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] A file list failed to reload after a change:', e);
+        }
+    }
+}
+/** Tests only. */
+function clearFilesRefreshers() {
+    refreshers.clear();
+}

package/dist/cjs/index.d.ts

@@ -23,6 +23,8 @@ export { KoolbaseStorage } from './storage.js';
 export { KoolbaseUploadTask } from './storage-transfer.js';
 export type { KoolbaseUploadProgress, KoolbaseUploadState } from './storage-transfer.js';
 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 { 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.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.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);
@@ -53,6 +53,11 @@ var storage_js_1 = require("./storage.js");
 Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: function () { return storage_js_1.KoolbaseStorage; } });
 var storage_transfer_js_1 = require("./storage-transfer.js");
 Object.defineProperty(exports, "KoolbaseUploadTask", { enumerable: true, get: function () { return storage_transfer_js_1.KoolbaseUploadTask; } });
+// A bucket's files as list state (storage S4).
+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; } });
 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,2 +1,3 @@
 export { createUseCollection, type UseCollectionResult } from './use-collection.js';
 export { createUseRecord, type UseRecordResult } from './use-record.js';
+export { createUseFiles, type UseFilesResult } from './use-files.js';

package/dist/cjs/react/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUseRecord = exports.createUseCollection = void 0;
+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
@@ -9,3 +9,5 @@ var use_collection_js_1 = require("./use-collection.js");
 Object.defineProperty(exports, "createUseCollection", { enumerable: true, get: function () { return use_collection_js_1.createUseCollection; } });
 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; } });

package/dist/cjs/react/use-files.d.ts

@@ -0,0 +1,8 @@
+import { type FilesQuery, type FilesState, type KoolbaseStorage } from '../index.js';
+export interface UseFilesResult extends FilesState {
+    /** Page one again. What is shown stays while it runs, and stays if it fails. */
+    refresh: () => Promise<void>;
+    /** The next page, appended, while hasMore. */
+    loadMore: () => Promise<void>;
+}
+export declare function createUseFiles(getStorage: () => Pick<KoolbaseStorage, 'listFiles'>): (bucket: string, query?: FilesQuery) => UseFilesResult;

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

@@ -0,0 +1,37 @@
+"use strict";
+// useFiles: a bucket's files as React state (storage S4).
+//
+// A thin wrapper. Everything about getting the files right lives in
+// @koolbase/core's KoolbaseFilesController, which is tested there; this
+// file only ties one controller's lifetime to a component's.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUseFiles = createUseFiles;
+const react_1 = require("react");
+const index_js_1 = require("../index.js");
+const noop = () => { };
+const done = () => Promise.resolve();
+function createUseFiles(getStorage) {
+    return function useFiles(bucket, query = {}) {
+        // The query as a value: an inline object is a new object every render,
+        // and must not start a new fetch every render.
+        const key = (0, index_js_1.filesQueryKey)(bucket, query);
+        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.KoolbaseFilesController(getStorage(), bucket, query);
+            setCurrent({ key, controller });
+            void controller.load();
+            return () => controller.dispose();
+        }, [key]);
+        // A controller from the previous key reads as a fresh load, never as
+        // the previous listing's files.
+        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.initialFilesState), [controller]);
+        const state = (0, react_1.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+        const refresh = (0, react_1.useCallback)(() => (controller ? controller.refresh() : done()), [controller]);
+        const loadMore = (0, react_1.useCallback)(() => (controller ? controller.loadMore() : done()), [controller]);
+        return { ...state, refresh, loadMore };
+    };
+}

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

@@ -226,6 +226,20 @@ export declare class KoolbaseStorageInvalidCursorError extends KoolbaseStorageEr
 export declare class KoolbaseStorageSignInRequiredError extends KoolbaseStorageError {
     constructor(message?: string);
 }
+/**
+ * Completing an upload in parts with parts missing or the wrong size (S3):
+ * resume it, which sends `missing`. Code: `upload_incomplete`.
+ */
+export declare class KoolbaseUploadIncompleteError extends KoolbaseStorageError {
+    missing: number[];
+    constructor(message?: string, missing?: number[]);
+}
+/**
+ * A download stopped by its `signal` (S3). Code: `download_cancelled`.
+ */
+export declare class KoolbaseDownloadCancelledError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
 /**
  * A move refused while records point at the file (S1b): `field` holds its
  * path in `records` records. Change those first, or copy the file. Code:

package/dist/cjs/storage-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStorageNameHasHistoryError = exports.KoolbaseStorageFileInUseError = exports.KoolbaseStorageSignInRequiredError = exports.KoolbaseStorageInvalidCursorError = exports.KoolbaseStorageBusyError = exports.KoolbaseUploadNotFoundError = exports.KoolbaseUploadCancelledError = exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseCapBelowUsageError = exports.KoolbaseUploadExpiredError = exports.KoolbaseUploadURLFailedError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageProjectIdentityError = exports.KoolbaseStorageError = void 0;
+exports.KoolbaseStorageNameHasHistoryError = exports.KoolbaseStorageFileInUseError = exports.KoolbaseDownloadCancelledError = exports.KoolbaseUploadIncompleteError = exports.KoolbaseStorageSignInRequiredError = exports.KoolbaseStorageInvalidCursorError = exports.KoolbaseStorageBusyError = exports.KoolbaseUploadNotFoundError = exports.KoolbaseUploadCancelledError = exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseCapBelowUsageError = exports.KoolbaseUploadExpiredError = exports.KoolbaseUploadURLFailedError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageProjectIdentityError = exports.KoolbaseStorageError = void 0;
 exports.koolbaseStorageError = koolbaseStorageError;
 exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
 const errors_js_1 = require("./errors.js");
@@ -316,6 +316,30 @@ class KoolbaseStorageSignInRequiredError extends KoolbaseStorageError {
     }
 }
 exports.KoolbaseStorageSignInRequiredError = KoolbaseStorageSignInRequiredError;
+/**
+ * Completing an upload in parts with parts missing or the wrong size (S3):
+ * resume it, which sends `missing`. Code: `upload_incomplete`.
+ */
+class KoolbaseUploadIncompleteError extends KoolbaseStorageError {
+    constructor(message, missing = []) {
+        super(message ?? 'The upload is missing parts; resume it', 'upload_incomplete');
+        this.missing = missing;
+        this.name = 'KoolbaseUploadIncompleteError';
+        Object.setPrototypeOf(this, KoolbaseUploadIncompleteError.prototype);
+    }
+}
+exports.KoolbaseUploadIncompleteError = KoolbaseUploadIncompleteError;
+/**
+ * A download stopped by its `signal` (S3). Code: `download_cancelled`.
+ */
+class KoolbaseDownloadCancelledError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The download was cancelled', 'download_cancelled');
+        this.name = 'KoolbaseDownloadCancelledError';
+        Object.setPrototypeOf(this, KoolbaseDownloadCancelledError.prototype);
+    }
+}
+exports.KoolbaseDownloadCancelledError = KoolbaseDownloadCancelledError;
 /**
  * A move refused while records point at the file (S1b): `field` holds its
  * path in `records` records. Change those first, or copy the file. Code:
@@ -397,6 +421,10 @@ function koolbaseStorageError(status, body, fallbackMessage = 'Storage request f
         }
         case 'name_has_history':
             return new KoolbaseStorageNameHasHistoryError(message);
+        case 'upload_incomplete': {
+            const d = (body?.details ?? {});
+            return new KoolbaseUploadIncompleteError(message, Array.isArray(d.missing) ? d.missing : []);
+        }
     }
     // ─── status fallback (pre-code servers or uncoded paths) ───
     switch (status) {

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

@@ -0,0 +1,29 @@
+import { KoolbaseUploadTask } from './storage-transfer.js';
+/** The server's plan for an upload in parts, and which parts arrived. */
+export interface MultipartPlan {
+    upload_id: string;
+    path: string;
+    size: number;
+    part_size: number;
+    part_count: number;
+    content_type: string;
+    uploaded?: number[];
+}
+/** What sending the parts needs from the server. */
+export interface MultipartApi {
+    links(parts: number[]): Promise<Record<string, string>>;
+    abort(): Promise<void>;
+}
+/** Parts in flight at once. */
+export declare const PARTS_AT_ONCE = 3;
+/** Tries per part. */
+export declare const PART_TRIES = 4;
+/** How long to wait before try `n` (1-based) of a part; tests shorten it. */
+export declare const partRetry: {
+    delayMs: (n: number) => number;
+};
+/**
+ * Sends the parts of `file` not yet in `plan.uploaded`, reporting the bytes
+ * of the whole file; resolves once every part has arrived.
+ */
+export declare function sendParts(task: KoolbaseUploadTask, plan: MultipartPlan, file: Blob, api: MultipartApi): Promise<void>;

package/dist/cjs/storage-multipart.js

@@ -0,0 +1,168 @@
+"use strict";
+// A large file's upload, in parts (S3).
+//
+// Each part goes straight to storage on its own signed link, three at a time.
+// A part that fails for a passing reason -- the network, storage busy -- is
+// sent again, up to four times, waiting longer each time; one whose link
+// has expired gets a new link. A failed upload is not abandoned: its id
+// (`KoolbaseUploadTask.uploadId`) resumes it, sending only the parts that
+// did not arrive. Cancelling abandons it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.partRetry = exports.PART_TRIES = exports.PARTS_AT_ONCE = void 0;
+exports.sendParts = sendParts;
+const storage_errors_js_1 = require("./storage-errors.js");
+const storage_transfer_js_1 = require("./storage-transfer.js");
+/** Parts in flight at once. */
+exports.PARTS_AT_ONCE = 3;
+/** Tries per part. */
+exports.PART_TRIES = 4;
+/** Links asked for at a time (the server signs at most 100 a call). */
+const LINKS_AT_ONCE = 50;
+/** How long to wait before try `n` (1-based) of a part; tests shorten it. */
+exports.partRetry = { delayMs: (n) => 500 * 2 ** (n - 1) };
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** A status a part may be sent again after. */
+const passing = (status) => status === 408 || status === 429 || status >= 500;
+/**
+ * Sends the parts of `file` not yet in `plan.uploaded`, reporting the bytes
+ * of the whole file; resolves once every part has arrived.
+ */
+async function sendParts(task, plan, file, api) {
+    const count = plan.part_count;
+    const partSize = plan.part_size;
+    const bounds = (n) => [(n - 1) * partSize, Math.min(n * partSize, plan.size)];
+    const arrived = new Set(plan.uploaded ?? []);
+    const sent = new Map();
+    for (const n of arrived) {
+        const [a, b] = bounds(n);
+        sent.set(n, b - a);
+    }
+    const report = () => {
+        if (task.cancelled)
+            return;
+        let total = 0;
+        for (const v of sent.values())
+            total += v;
+        task.emit('uploading', Math.min(total, plan.size));
+    };
+    report();
+    const todo = [];
+    for (let n = 1; n <= count; n++)
+        if (!arrived.has(n))
+            todo.push(n);
+    // Links, asked for a few at a time -- one request for parts in flight at
+    // once, not one each -- and renewed when one has expired.
+    const links = new Map();
+    const asking = new Map();
+    const ask = (parts) => {
+        const p = api.links(parts).then((got) => {
+            for (const [k, v] of Object.entries(got))
+                links.set(Number(k), v);
+        });
+        for (const n of parts)
+            asking.set(n, p);
+        return p.finally(() => {
+            for (const n of parts)
+                if (asking.get(n) === p)
+                    asking.delete(n);
+        });
+    };
+    const linkFor = async (n, fresh = false) => {
+        if (fresh) {
+            links.delete(n);
+            await ask([n]);
+        }
+        else if (!links.has(n)) {
+            if (asking.has(n))
+                await asking.get(n);
+            else {
+                const from = Math.max(todo.indexOf(n), 0);
+                await ask(todo.slice(from, from + LINKS_AT_ONCE).filter((p) => p === n || (!links.has(p) && !asking.has(p))));
+            }
+        }
+        const url = links.get(n);
+        if (!url)
+            throw new storage_errors_js_1.KoolbaseStorageError(`No upload link for part ${n}`);
+        return url;
+    };
+    // Every transfer in flight, so a cancel stops them all.
+    const flying = new Set();
+    task.setAbort(() => {
+        for (const t of flying)
+            t.abort();
+    });
+    const sendOne = async (n) => {
+        const [a, b] = bounds(n);
+        const body = file.slice(a, b);
+        let fresh = false;
+        for (let attempt = 1;; attempt++) {
+            task.checkCancelled();
+            const url = await linkFor(n, fresh);
+            fresh = false;
+            task.checkCancelled();
+            sent.set(n, 0);
+            report();
+            const t = (0, storage_transfer_js_1.transferBytes)(url, body, null, (s) => {
+                sent.set(n, s);
+                report();
+            });
+            flying.add(t);
+            let status = 0;
+            let failure = null;
+            try {
+                status = (await t.done).status;
+            }
+            catch (e) {
+                failure = e;
+            }
+            finally {
+                flying.delete(t);
+            }
+            task.checkCancelled();
+            if (failure === null && status >= 200 && status < 300) {
+                sent.set(n, b - a);
+                report();
+                return;
+            }
+            if (failure instanceof storage_errors_js_1.KoolbaseUploadCancelledError)
+                throw failure;
+            sent.set(n, 0);
+            report();
+            const again = failure !== null || passing(status) || status === 403;
+            if (!again || attempt >= exports.PART_TRIES) {
+                throw failure ?? new storage_errors_js_1.KoolbaseStorageError(`Upload of part ${n} failed: ${status}`);
+            }
+            // An expired link (403) is renewed; anything else waits and tries again.
+            if (status === 403)
+                fresh = true;
+            else
+                await sleep(exports.partRetry.delayMs(attempt));
+        }
+    };
+    try {
+        let next = 0;
+        const worker = async () => {
+            while (next < todo.length) {
+                const n = todo[next++];
+                await sendOne(n);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(exports.PARTS_AT_ONCE, todo.length) }, worker));
+    }
+    catch (e) {
+        // One part failing stops the rest; the parts that arrived stay, for a
+        // resume -- unless the upload was cancelled, which abandons it.
+        for (const t of flying)
+            t.abort();
+        if (task.cancelled) {
+            await api.abort().catch(() => undefined);
+            throw new storage_errors_js_1.KoolbaseUploadCancelledError();
+        }
+        throw e;
+    }
+    finally {
+        task.setAbort(null);
+    }
+}