@bejibun/storage 0.1.1 → 0.1.11

package/builders/StorageBuilder.d.ts

@@ -1,24 +1,141 @@
 import type { Stats } from "fs";
 import type { StorageDisk, StorageOptions } from "../types/storage";
+/**
+ * Builds and dispatches storage operations to the configured disk driver.
+ */
 export default class StorageBuilder {
+    /** The loaded storage configuration. */
     protected conf: Record<string, any>;
+    /** An optional disk override applied when building a driver. */
     protected overrideDisk?: StorageDisk;
+    /** The name of the selected disk. */
     protected drive?: string;
+    /**
+     * Load the storage configuration from the app config or the built-in default.
+     */
     constructor();
+    /**
+     * Get the storage configuration, throwing if it is empty.
+     *
+     * @returns {Record<string, any>} The storage configuration.
+     * @throws {StorageException} When no configuration is provided.
+     */
     private get config();
+    /**
+     * Get the configuration for the current disk.
+     *
+     * @returns {any} The current disk configuration.
+     */
     private get currentDisk();
+    /**
+     * Resolve the driver instance for the current disk.
+     *
+     * @returns {StorageDriver} The resolved storage driver.
+     * @throws {StorageException} When the driver is missing or unsupported.
+     */
     private get driver();
+    /**
+     * Override the disk used for subsequent operations.
+     *
+     * @param {StorageDisk} overrideDisk - The disk configuration to use.
+     * @returns {StorageBuilder} This builder instance.
+     */
     build(overrideDisk: StorageDisk): StorageBuilder;
+    /**
+     * Select the disk by name for subsequent operations.
+     *
+     * @param {string} drive - The name of the disk to use.
+     * @returns {StorageBuilder} This builder instance.
+     */
     disk(drive: string): StorageBuilder;
+    /**
+     * Determine whether a file exists.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<boolean>} True if the file exists; otherwise false.
+     * @throws {StorageException} When the file path is empty.
+     */
     exists(filepath: string): Promise<boolean>;
+    /**
+     * Determine whether a file is missing.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<boolean>} True if the file does not exist; otherwise false.
+     * @throws {StorageException} When the file path is empty.
+     */
     missing(filepath: string): Promise<boolean>;
+    /**
+     * Retrieve metadata for a file.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Stats | Bun.S3Stats>} File metadata and statistics.
+     * @throws {StorageException} When the file path is empty.
+     */
     metadata(filepath: string): Promise<Stats | Bun.S3Stats>;
+    /**
+     * Get the file size in bytes.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<number>} The file size in bytes.
+     * @throws {StorageException} When the file path is empty.
+     */
     size(filepath: string): Promise<number>;
+    /**
+     * Get the file MIME type.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<string>} The detected MIME type.
+     * @throws {StorageException} When the file path is empty.
+     */
     mimeType(filepath: string): Promise<string>;
+    /**
+     * Get the file's last modification date.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Date>} The last modified timestamp.
+     * @throws {StorageException} When the file path is empty.
+     */
     lastModified(filepath: string): Promise<Date>;
+    /**
+     * Retrieve a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Bun.BunFile | Bun.S3File>} The storage file instance.
+     * @throws {StorageException} When the file path is empty.
+     */
     get(filepath: string): Promise<Bun.BunFile | Bun.S3File>;
+    /**
+     * Store content at the given path.
+     *
+     * @param {string} filepath - The destination file path.
+     * @param {any} content - The content to store.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the file path or content is empty.
+     */
     put(filepath: string, content: any, options?: StorageOptions): Promise<void>;
+    /**
+     * Copy a file to a new location.
+     *
+     * @param {string} source - The source file path.
+     * @param {string} destination - The destination file path.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the source or destination path is empty.
+     */
     copy(source: string, destination: string, options?: StorageOptions): Promise<void>;
+    /**
+     * Move a file to a new location.
+     *
+     * @param {string} source - The source file path.
+     * @param {string} destination - The destination file path.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the source or destination path is empty.
+     */
     move(source: string, destination: string, options?: StorageOptions): Promise<void>;
+    /**
+     * Delete a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @throws {StorageException} When the file path is empty.
+     */
     delete(filepath: string): Promise<void>;
 }

package/builders/StorageBuilder.js

@@ -1,37 +1,73 @@
 import App from "@bejibun/app";
 import Logger from "@bejibun/logger";
-import { defineValue, isEmpty } from "@bejibun/utils";
+import { defineValue } from "@bejibun/utils";
 import Enum from "@bejibun/utils/facades/Enum";
-import fs from "fs";
-import StorageLocalBuilder from "../builders/storage/StorageLocalBuilder";
-import StorageS3Builder from "../builders/storage/StorageS3Builder";
-import StorageConfig from "../config/storage";
+import StorageLocalBuilder from "./storage/StorageLocalBuilder";
+import StorageS3Builder from "./storage/StorageS3Builder";
 import StorageDiskDriverEnum from "../enums/StorageDiskDriverEnum";
 import StorageException from "../exceptions/StorageException";
+/** The app storage config, loaded once from disk. */
+let cachedConfig;
+/**
+ * Loads the app storage config from disk once, falling back to the built-in default.
+ *
+ * @returns {any} The loaded storage configuration.
+ */
+const loadConfig = () => {
+    if (cachedConfig)
+        return cachedConfig;
+    try {
+        cachedConfig = require(App.Path.configPath("storage.ts")).default;
+    }
+    catch {
+        cachedConfig = require("../config/storage").default;
+    }
+    return cachedConfig;
+};
+/**
+ * Builds and dispatches storage operations to the configured disk driver.
+ */
 export default class StorageBuilder {
+    /** The loaded storage configuration. */
     conf;
+    /** An optional disk override applied when building a driver. */
     overrideDisk;
+    /** The name of the selected disk. */
     drive;
+    /**
+     * Load the storage configuration from the app config or the built-in default.
+     */
     constructor() {
-        const configPath = App.Path.configPath("storage.ts");
-        let config;
-        if (fs.existsSync(configPath))
-            config = require(configPath).default;
-        else
-            config = StorageConfig;
-        this.conf = config;
+        this.conf = loadConfig();
     }
+    /**
+     * Get the storage configuration, throwing if it is empty.
+     *
+     * @returns {Record<string, any>} The storage configuration.
+     * @throws {StorageException} When no configuration is provided.
+     */
     get config() {
-        if (isEmpty(this.conf))
+        if (!this.conf)
             throw new StorageException("There is no config provided.");
         return this.conf;
     }
+    /**
+     * Get the configuration for the current disk.
+     *
+     * @returns {any} The current disk configuration.
+     */
     get currentDisk() {
         return defineValue(this.overrideDisk, this.config.disks[defineValue(this.drive, this.config.default)]);
     }
+    /**
+     * Resolve the driver instance for the current disk.
+     *
+     * @returns {StorageDriver} The resolved storage driver.
+     * @throws {StorageException} When the driver is missing or unsupported.
+     */
     get driver() {
         const driver = defineValue(this.currentDisk?.driver);
-        if (isEmpty(driver))
+        if (!driver)
             throw new StorageException(`Missing "driver" on disk config.`);
         if (!Enum.setEnums(StorageDiskDriverEnum).hasValue(driver))
             throw new StorageException(`Not supported "driver" disk.`);
@@ -44,53 +80,122 @@ export default class StorageBuilder {
                 throw new StorageException(`Not supported "driver" disk.`);
         }
     }
+    /**
+     * Override the disk used for subsequent operations.
+     *
+     * @param {StorageDisk} overrideDisk - The disk configuration to use.
+     * @returns {StorageBuilder} This builder instance.
+     */
     build(overrideDisk) {
         this.overrideDisk = overrideDisk;
         return this;
     }
+    /**
+     * Select the disk by name for subsequent operations.
+     *
+     * @param {string} drive - The name of the disk to use.
+     * @returns {StorageBuilder} This builder instance.
+     */
     disk(drive) {
         this.drive = drive;
         return this;
     }
+    /**
+     * Determine whether a file exists.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<boolean>} True if the file exists; otherwise false.
+     * @throws {StorageException} When the file path is empty.
+     */
     async exists(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.driver.exists(filepath);
     }
+    /**
+     * Determine whether a file is missing.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<boolean>} True if the file does not exist; otherwise false.
+     * @throws {StorageException} When the file path is empty.
+     */
     async missing(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
-        return !(await this.driver.missing(filepath));
+        return await this.driver.missing(filepath);
     }
+    /**
+     * Retrieve metadata for a file.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Stats | Bun.S3Stats>} File metadata and statistics.
+     * @throws {StorageException} When the file path is empty.
+     */
     async metadata(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.driver.metadata(filepath);
     }
+    /**
+     * Get the file size in bytes.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<number>} The file size in bytes.
+     * @throws {StorageException} When the file path is empty.
+     */
     async size(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.driver.size(filepath);
     }
+    /**
+     * Get the file MIME type.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<string>} The detected MIME type.
+     * @throws {StorageException} When the file path is empty.
+     */
     async mimeType(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.driver.mimeType(filepath);
     }
+    /**
+     * Get the file's last modification date.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Date>} The last modified timestamp.
+     * @throws {StorageException} When the file path is empty.
+     */
     async lastModified(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.driver.lastModified(filepath);
     }
+    /**
+     * Retrieve a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Bun.BunFile | Bun.S3File>} The storage file instance.
+     * @throws {StorageException} When the file path is empty.
+     */
     async get(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.driver.get(filepath);
     }
+    /**
+     * Store content at the given path.
+     *
+     * @param {string} filepath - The destination file path.
+     * @param {any} content - The content to store.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the file path or content is empty.
+     */
     async put(filepath, content, options) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
-        if (isEmpty(content))
+        if (!content)
             throw new StorageException("The content is required.");
         try {
             await this.driver.put(filepath, content, options);
@@ -101,10 +206,18 @@ export default class StorageBuilder {
                 .trace(error);
         }
     }
+    /**
+     * Copy a file to a new location.
+     *
+     * @param {string} source - The source file path.
+     * @param {string} destination - The destination file path.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the source or destination path is empty.
+     */
     async copy(source, destination, options) {
-        if (isEmpty(source))
+        if (!source)
             throw new StorageException("The source file path is required.");
-        if (isEmpty(destination))
+        if (!destination)
             throw new StorageException("The destination file path is required.");
         try {
             await this.driver.copy(source, destination, options);
@@ -115,10 +228,18 @@ export default class StorageBuilder {
                 .trace(error);
         }
     }
+    /**
+     * Move a file to a new location.
+     *
+     * @param {string} source - The source file path.
+     * @param {string} destination - The destination file path.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the source or destination path is empty.
+     */
     async move(source, destination, options) {
-        if (isEmpty(source))
+        if (!source)
             throw new StorageException("The source file path is required.");
-        if (isEmpty(destination))
+        if (!destination)
             throw new StorageException("The destination file path is required.");
         try {
             await this.driver.move(source, destination, options);
@@ -129,8 +250,14 @@ export default class StorageBuilder {
                 .trace(error);
         }
     }
+    /**
+     * Delete a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @throws {StorageException} When the file path is empty.
+     */
     async delete(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         await this.driver.delete(filepath);
     }

package/builders/storage/StorageLocalBuilder.d.ts

@@ -1,18 +1,107 @@
 import type { Stats } from "fs";
 import type { StorageDriver, StorageOptions } from "../../types/storage";
+/**
+ * Local filesystem storage driver backed by Bun file utilities.
+ */
 export default class StorageLocalBuilder implements StorageDriver {
+    /** The Local disk configuration. */
     protected _config: Record<string, any>;
+    /**
+     * Create a local storage driver from disk configuration.
+     *
+     * @param {Record<string, any>} config - The local disk configuration.
+     * @throws {StorageException} When the root path is missing.
+     */
     constructor(config: Record<string, any>);
     private get config();
+    /**
+     * Determine whether a file exists.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<boolean>} True if the file exists; otherwise false.
+     * @throws {StorageException} When the file path is empty.
+     */
     exists(filepath: string): Promise<boolean>;
+    /**
+     * Determine whether a file is missing.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<boolean>} True if the file does not exist; otherwise false.
+     * @throws {StorageException} When the file path is empty.
+     */
     missing(filepath: string): Promise<boolean>;
+    /**
+     * Retrieve metadata for a file.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Stats>} File metadata and statistics.
+     * @throws {StorageException} When the file path is empty.
+     */
     metadata(filepath: string): Promise<Stats>;
+    /**
+     * Get the file size in bytes.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<number>} The file size in bytes.
+     * @throws {StorageException} When the file path is empty.
+     */
     size(filepath: string): Promise<number>;
+    /**
+     * Get the file MIME type.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<string>} The detected MIME type.
+     * @throws {StorageException} When the file path is empty.
+     */
     mimeType(filepath: string): Promise<string>;
+    /**
+     * Get the file's last modification date.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Date>} The last modified timestamp.
+     * @throws {StorageException} When the file path is empty.
+     */
     lastModified(filepath: string): Promise<Date>;
+    /**
+     * Retrieve a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Bun.BunFile>} The local file instance.
+     * @throws {StorageException} When the file path is empty.
+     */
     get(filepath: string): Promise<Bun.BunFile>;
+    /**
+     * Store content at the given path.
+     *
+     * @param {string} filepath - The destination file path.
+     * @param {any} content - The content to store.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the file path or content is empty.
+     */
     put(filepath: string, content: any, options?: StorageOptions): Promise<void>;
+    /**
+     * Copy a file to a new location.
+     *
+     * @param {string} source - The source file path.
+     * @param {string} destination - The destination file path.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the source or destination path is empty.
+     */
     copy(source: string, destination: string, options?: StorageOptions): Promise<void>;
+    /**
+     * Move a file to a new location.
+     *
+     * @param {string} source - The source file path.
+     * @param {string} destination - The destination file path.
+     * @param {StorageOptions} options - Additional storage options.
+     * @throws {StorageException} When the source or destination path is empty.
+     */
     move(source: string, destination: string, options?: StorageOptions): Promise<void>;
+    /**
+     * Delete a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @throws {StorageException} When the file path is empty.
+     */
     delete(filepath: string): Promise<void>;
 }