@koolbase/core 12.19.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/index.d.ts

@@ -25,6 +25,8 @@ export type { KoolbaseUploadProgress, KoolbaseUploadState } from './storage-tran
 export type { KoolbaseFileInfo, KoolbaseFilePage, KoolbaseFileSort, ListFilesOptions } from './storage-files.js';
 export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './files-controller.js';
 export type { FilesQuery, FilesState, FilesStatus } from './files-controller.js';
+export { KoolbaseFileController, initialFileState } from './file-controller.js';
+export type { FileState, FileStatus } from './file-controller.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';

package/dist/cjs/index.js

@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.filesQueryKey = exports.initialFilesState = exports.KoolbaseFilesController = exports.KoolbaseUploadTask = exports.KoolbaseStorage = exports.KoolbaseConnectivity = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
+exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.initialFileState = exports.KoolbaseFileController = exports.filesQueryKey = exports.initialFilesState = exports.KoolbaseFilesController = exports.KoolbaseUploadTask = exports.KoolbaseStorage = exports.KoolbaseConnectivity = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./network.js"), exports);
@@ -58,6 +58,10 @@ 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,3 +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.createUseFiles = 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
@@ -11,3 +11,5 @@ 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/esm/file-controller.d.ts

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

package/dist/esm/file-controller.js

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

package/dist/esm/index.d.ts

@@ -25,6 +25,8 @@ export type { KoolbaseUploadProgress, KoolbaseUploadState } from './storage-tran
 export type { KoolbaseFileInfo, KoolbaseFilePage, KoolbaseFileSort, ListFilesOptions } from './storage-files.js';
 export { KoolbaseFilesController, initialFilesState, filesQueryKey } from './files-controller.js';
 export type { FilesQuery, FilesState, FilesStatus } from './files-controller.js';
+export { KoolbaseFileController, initialFileState } from './file-controller.js';
+export type { FileState, FileStatus } from './file-controller.js';
 export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';

package/dist/esm/index.js

@@ -25,6 +25,8 @@ 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,3 +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

@@ -5,3 +5,4 @@
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.19.0",
+  "version": "12.20.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",