@bejibun/storage 0.1.0 → 0.1.11

package/benchmarks/scripts/throughput.mjs

@@ -0,0 +1,83 @@
+/**
+ * Throughput benchmark.
+ *
+ * Measures the hot paths touched on every storage operation, method by method. On baseline
+ * each `new StorageBuilder()` re-reads the config file from disk (`fs.existsSync` +
+ * `require()`) and re-resolves the driver; the optimized build caches the resolved config
+ * at module load and uses native nullish checks instead of `defineValue`/`isEmpty`.
+ * `exists`/`get`/`delete` exercise the full facade path against a temporary local disk.
+ *
+ * Run: bun run scripts/throughput.mjs
+ */
+import {spawnSync} from "node:child_process";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+import {printTable} from "./table-format.mjs";
+import {updateReadmeSection} from "./readme-writer.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TRIALS = 9;
+const runtime = process.execPath;
+
+function runTrials(scriptPath) {
+    const results = [];
+    for (let i = 0; i < TRIALS; i++) {
+        const res = spawnSync(runtime, [scriptPath], {encoding: "utf8"});
+        if (res.status !== 0) {
+            console.error("Benchmark failed:", res.stderr);
+            process.exit(1);
+        }
+        results.push(res.stdout.trim().split("|").map(Number));
+    }
+    return results;
+}
+
+function medianRow(trials) {
+    const cols = trials[0].length;
+    const medians = [];
+    for (let c = 0; c < cols; c++) {
+        const sorted = trials.map((t) => t[c]).sort((a, b) => a - b);
+        medians.push(sorted[Math.floor(sorted.length / 2)]);
+    }
+    return medians;
+}
+
+const ITERATIONS = 20_000;
+const methods = ["construction", "exists", "get", "delete"];
+const bCols = medianRow(runTrials(path.join(__dirname, "throughput-baseline.mjs")));
+const oCols = medianRow(runTrials(path.join(__dirname, "throughput-optimized.mjs")));
+
+function fmt(ms) {
+    return ms < 1 ? `${(ms * 1000).toFixed(0)}\u00B5s` : `${ms.toFixed(1)}ms`;
+}
+
+function sp(b, o) {
+    const r = b / o;
+    return r >= 1.05 ? `${r.toFixed(2)}x` : r <= 0.95 ? `${r.toFixed(2)}x` : "~1.0x";
+}
+
+function ops(ms) {
+    return Math.round(ITERATIONS / (ms / 1000)).toLocaleString() + "/s";
+}
+
+const rows = methods.map((m, i) => ({
+    cells: [m, fmt(bCols[i]), fmt(oCols[i]), sp(bCols[i], oCols[i]), ops(oCols[i])]
+}));
+
+printTable({
+    title: "THROUGHPUT BENCHMARK",
+    subtitle: `${ITERATIONS.toLocaleString()} calls each, ${TRIALS} runs (median)`,
+    headers: ["Method", "Baseline (0.1.1)", "Optimized", "Speedup", "Optimized ops/s"],
+    rows
+});
+
+const lines = [
+    "| Method | baseline (0.1.1) | optimized | speedup | baseline ops/s | optimized ops/s |",
+    "|---|---|---|---|---|---|",
+    ...methods.map(
+        (m, i) =>
+            `| \`${m}\` | ${bCols[i].toFixed(1)}ms | ${oCols[i].toFixed(1)}ms | **${(bCols[i] / oCols[i]).toFixed(2)}x** | ${ops(bCols[i])} | ${ops(oCols[i])} |`
+    )
+];
+
+updateReadmeSection("THROUGHPUT", lines.join("\n"));

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,87 +80,184 @@ 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);
         }
         catch (error) {
-            Logger.setContext("Storage").error("Something went wrong when saving file.").trace(error);
+            Logger.setContext("Storage")
+                .error("Something went wrong when saving file.")
+                .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);
         }
         catch (error) {
-            Logger.setContext("Storage").error("Something went wrong when copying file.").trace(error);
+            Logger.setContext("Storage")
+                .error("Something went wrong when copying file.")
+                .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);
         }
         catch (error) {
-            Logger.setContext("Storage").error("Something went wrong when moving file.").trace(error);
+            Logger.setContext("Storage")
+                .error("Something went wrong when moving file.")
+                .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>;
 }