@koolbase/core 12.18.0 → 12.20.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/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,10 @@ 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 { KoolbaseFileController, initialFileState } from './file-controller.js';
+export type { FileState, FileStatus } from './file-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.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);
@@ -53,6 +53,15 @@ 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; } });
+// 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; } });
 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,4 @@
 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';

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.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
@@ -9,3 +9,7 @@ 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; } });
+var use_file_js_1 = require("./use-file.js");
+Object.defineProperty(exports, "createUseFile", { enumerable: true, get: function () { return use_file_js_1.createUseFile; } });

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-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 };
+    };
+}