@koolbase/core 12.17.0 → 12.19.0

package/dist/esm/files-controller.js

@@ -0,0 +1,155 @@
+// 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
+import { registerFilesRefresher } from './files-refresh.js';
+export const initialFilesState = Object.freeze({
+    status: 'loading',
+    files: Object.freeze([]),
+    error: null,
+    refreshing: false,
+    loadingMore: false,
+    hasMore: true,
+});
+/** One string per distinct listing. */
+export 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;
+}
+export class KoolbaseFilesController {
+    constructor(storage, bucket, query = {}) {
+        this.state = 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 = 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();
+    }
+}

package/dist/esm/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/esm/files-refresh.js

@@ -0,0 +1,34 @@
+// 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.
+const refreshers = new Map();
+let next = 0;
+/** Registers one file list's reload; returns the unregister. */
+export 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.
+ */
+export 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. */
+export function clearFilesRefreshers() {
+    refreshers.clear();
+}

package/dist/esm/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/esm/index.js

@@ -23,6 +23,8 @@ export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseConnectivity } from './connectivity.js';
 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';
 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,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/esm/react/index.js

@@ -4,3 +4,4 @@
 // core's root entry, so importing @koolbase/core never loads React.
 export { createUseCollection } from './use-collection.js';
 export { createUseRecord } from './use-record.js';
+export { createUseFiles } from './use-files.js';

package/dist/esm/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/esm/react/use-files.js

@@ -0,0 +1,34 @@
+// 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.
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import { KoolbaseFilesController, filesQueryKey, initialFilesState, } from '../index.js';
+const noop = () => { };
+const done = () => Promise.resolve();
+export 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 = filesQueryKey(bucket, query);
+        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 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 = useCallback((onChange) => (controller ? controller.subscribe(onChange) : noop), [controller]);
+        const getSnapshot = useCallback(() => (controller ? controller.getState() : initialFilesState), [controller]);
+        const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+        const refresh = useCallback(() => (controller ? controller.refresh() : done()), [controller]);
+        const loadMore = useCallback(() => (controller ? controller.loadMore() : done()), [controller]);
+        return { ...state, refresh, loadMore };
+    };
+}

package/dist/esm/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/esm/storage-errors.js

@@ -293,6 +293,28 @@ export class KoolbaseStorageSignInRequiredError extends KoolbaseStorageError {
         Object.setPrototypeOf(this, KoolbaseStorageSignInRequiredError.prototype);
     }
 }
+/**
+ * Completing an upload in parts with parts missing or the wrong size (S3):
+ * resume it, which sends `missing`. Code: `upload_incomplete`.
+ */
+export 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);
+    }
+}
+/**
+ * A download stopped by its `signal` (S3). Code: `download_cancelled`.
+ */
+export class KoolbaseDownloadCancelledError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The download was cancelled', 'download_cancelled');
+        this.name = 'KoolbaseDownloadCancelledError';
+        Object.setPrototypeOf(this, KoolbaseDownloadCancelledError.prototype);
+    }
+}
 /**
  * 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:
@@ -372,6 +394,10 @@ export function koolbaseStorageError(status, body, fallbackMessage = 'Storage re
         }
         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/esm/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/esm/storage-multipart.js

@@ -0,0 +1,164 @@
+// 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.
+import { KoolbaseStorageError, KoolbaseUploadCancelledError } from './storage-errors.js';
+import { transferBytes } from './storage-transfer.js';
+/** Parts in flight at once. */
+export const PARTS_AT_ONCE = 3;
+/** Tries per part. */
+export const 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. */
+export const 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.
+ */
+export 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 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 = 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 KoolbaseUploadCancelledError)
+                throw failure;
+            sent.set(n, 0);
+            report();
+            const again = failure !== null || passing(status) || status === 403;
+            if (!again || attempt >= PART_TRIES) {
+                throw failure ?? new 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(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(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 KoolbaseUploadCancelledError();
+        }
+        throw e;
+    }
+    finally {
+        task.setAbort(null);
+    }
+}

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

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