@koolbase/core 12.18.0 → 12.20.0

package/dist/cjs/storage.js

@@ -8,8 +8,14 @@ const storage_errors_js_2 = require("./storage-errors.js");
 const storage_transfer_js_1 = require("./storage-transfer.js");
 const storage_multipart_js_1 = require("./storage-multipart.js");
 const storage_errors_js_3 = require("./storage-errors.js");
+const files_refresh_js_1 = require("./files-refresh.js");
 const network_js_2 = require("./network.js");
 const storage_files_js_1 = require("./storage-files.js");
+/** An upload task whose success reloads the bucket's file lists (storage S4). */
+function listsReload(task, bucket) {
+    task.result.then(() => { void (0, files_refresh_js_1.refreshBucketFiles)(bucket); }, () => { });
+    return task;
+}
 // --- Cloudflare image-transform URL helpers -------------------------------
 // Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
 function clampInt(v, min, max) {
@@ -132,7 +138,7 @@ class KoolbaseStorage {
      * const { object } = await task.result;
      */
     startUpload(options) {
-        return (0, storage_transfer_js_1.runUploadTask)((task) => this.runUpload(options, task));
+        return listsReload((0, storage_transfer_js_1.runUploadTask)((task) => this.runUpload(options, task)), options.bucket);
     }
     async runUpload(options, task) {
         task.checkCancelled();
@@ -242,14 +248,14 @@ class KoolbaseStorage {
      * await Koolbase.storage.resumeUpload({ bucket: 'video', uploadId, file }).result;
      */
     resumeUpload(options) {
-        return (0, storage_transfer_js_1.runUploadTask)(async (task) => {
+        return listsReload((0, storage_transfer_js_1.runUploadTask)(async (task) => {
             const isBlob = typeof Blob !== 'undefined' && options.file instanceof Blob;
             const blob = isBlob
                 ? options.file
                 : await (await (0, network_js_1.sessionFetch)(options.file.uri)).blob();
             task.setTotal(blob.size);
             return this.runInParts(options.bucket, options, task, blob, '', options.uploadId);
-        });
+        }), options.bucket);
     }
     async runInParts(bucket, options, task, file, contentType, resumeId) {
         const base = `${this.config.baseUrl}/v1/sdk/storage/uploads`;
@@ -466,7 +472,9 @@ class KoolbaseStorage {
         if (!res.ok) {
             throw await this.error(res, op === 'move' ? 'Failed to move the file' : 'Failed to copy the file');
         }
-        return mapObjectFromServer(await res.json());
+        const moved = mapObjectFromServer(await res.json());
+        void (0, files_refresh_js_1.refreshBucketFiles)(o.bucket, ...(o.toBucket && o.toBucket !== o.bucket ? [o.toBucket] : []));
+        return moved;
     }
     /**
      * Apply a partial metadata update to an existing object. Returns the
@@ -514,6 +522,7 @@ class KoolbaseStorage {
             throw await this.error(res, 'Failed to update metadata');
         }
         const raw = await res.json();
+        void (0, files_refresh_js_1.refreshBucketFiles)(bucket);
         return mapObjectFromServer(raw);
     }
     /**
@@ -645,11 +654,11 @@ class KoolbaseStorage {
             },
             body: JSON.stringify({ bucket, path }),
         });
-        if (res.status === 204)
+        if (res.ok) {
+            void (0, files_refresh_js_1.refreshBucketFiles)(bucket);
             return;
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to delete file');
         }
+        throw await this.error(res, 'Failed to delete file');
     }
     /**
      * List all versions of a file path, newest-first. Returns a flat list
@@ -706,7 +715,9 @@ class KoolbaseStorage {
         if (!res.ok) {
             throw await this.error(res, 'Failed to restore version');
         }
-        return mapObjectFromServer(await res.json());
+        const restored = mapObjectFromServer(await res.json());
+        void (0, files_refresh_js_1.refreshBucketFiles)(bucket);
+        return restored;
     }
     /**
      * Hard-remove a single history version — both the metadata row and

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

@@ -23,6 +23,10 @@ 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';
+// One file's details as state (storage S4).
+export { KoolbaseFileController, initialFileState } from './file-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,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/esm/react/index.js

@@ -4,3 +4,5 @@
 // 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';
+export { createUseFile } from './use-file.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-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 };
+    };
+}