@bejibun/storage 0.1.1 → 0.1.11

package/builders/storage/StorageLocalBuilder.js

@@ -1,59 +1,125 @@
 import Logger from "@bejibun/logger";
-import { isEmpty } from "@bejibun/utils";
-import path from "path";
+import { resolve } from "path";
 import StorageException from "../../exceptions/StorageException";
+/**
+ * Local filesystem storage driver backed by Bun file utilities.
+ */
 export default class StorageLocalBuilder {
+    /** The Local disk configuration. */
     _config;
+    /**
+     * 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) {
         this._config = config;
     }
     get config() {
-        if (isEmpty(this._config.root))
+        if (!this._config.root)
             throw new StorageException(`Missing "root" for "local" disk configuration.`);
         return this._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.
+     */
     async exists(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
-        return await Bun.file(path.resolve(this.config.root, filepath)).exists();
+        return await Bun.file(resolve(this.config.root, filepath)).exists();
     }
+    /**
+     * 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.exists(filepath));
     }
+    /**
+     * 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.
+     */
     async metadata(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await (await this.get(filepath)).stat();
     }
+    /**
+     * 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.metadata(filepath)).size;
     }
+    /**
+     * 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.get(filepath)).type;
     }
+    /**
+     * 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.metadata(filepath)).mtime;
     }
+    /**
+     * 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.
+     */
     async get(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
-        return Bun.file(path.resolve(this.config.root, filepath));
+        return Bun.file(resolve(this.config.root, 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 Bun.write(path.resolve(this.config.root, filepath), content, options);
+            await Bun.write(resolve(this.config.root, filepath), content, options);
         }
         catch (error) {
             Logger.setContext("Storage")
@@ -61,10 +127,18 @@ export default class StorageLocalBuilder {
                 .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.put(destination, await this.get(source), options);
@@ -75,10 +149,18 @@ export default class StorageLocalBuilder {
                 .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.copy(source, destination, options);
@@ -90,9 +172,15 @@ export default class StorageLocalBuilder {
                 .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 Bun.file(path.resolve(this.config.root, filepath)).delete();
+        await Bun.file(resolve(this.config.root, filepath)).delete();
     }
 }

package/builders/storage/StorageS3Builder.d.ts

@@ -1,18 +1,108 @@
 import type { StorageDriver, StorageOptions } from "../../types/storage";
+/**
+ * S3-compatible storage driver backed by a Bun S3 client.
+ */
 export default class StorageS3Builder implements StorageDriver {
+    /** The S3 disk configuration. */
     protected _config: Record<string, any>;
+    /** The underlying S3 client. */
     protected client: Bun.S3Client;
+    /**
+     * Create an S3 storage driver from disk configuration.
+     *
+     * @param {Record<string, any>} config - The S3 disk configuration.
+     * @throws {StorageException} When the endpoint, access key id, or secret access key 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<Bun.S3Stats>} File metadata and statistics.
+     * @throws {StorageException} When the file path is empty.
+     */
     metadata(filepath: string): Promise<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.S3File>} The S3 file instance.
+     * @throws {StorageException} When the file path is empty.
+     */
     get(filepath: string): Promise<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/storage/StorageS3Builder.js

@@ -1,9 +1,19 @@
 import Logger from "@bejibun/logger";
-import { isEmpty } from "@bejibun/utils";
 import StorageException from "../../exceptions/StorageException";
+/**
+ * S3-compatible storage driver backed by a Bun S3 client.
+ */
 export default class StorageS3Builder {
+    /** The S3 disk configuration. */
     _config;
+    /** The underlying S3 client. */
     client;
+    /**
+     * Create an S3 storage driver from disk configuration.
+     *
+     * @param {Record<string, any>} config - The S3 disk configuration.
+     * @throws {StorageException} When the endpoint, access key id, or secret access key is missing.
+     */
     constructor(config) {
         this._config = config;
         this.client = new Bun.S3Client({
@@ -15,53 +25,110 @@ export default class StorageS3Builder {
         });
     }
     get config() {
-        if (isEmpty(this._config.endpoint))
+        if (!this._config.endpoint)
             throw new StorageException(`Missing "endpoint" for "s3" disk configuration.`);
-        if (isEmpty(this._config.access_key_id))
+        if (!this._config.access_key_id)
             throw new StorageException(`Missing "access_key_id" for "s3" disk configuration.`);
-        if (isEmpty(this._config.secret_access_key))
+        if (!this._config.secret_access_key)
             throw new StorageException(`Missing "secret_access_key" for "s3" disk configuration.`);
         return this._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.
+     */
     async exists(filepath) {
-        if (isEmpty(filepath))
+        if (!filepath)
             throw new StorageException("The file path is required.");
         return await this.client.file(filepath).exists();
     }
+    /**
+     * 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.exists(filepath));
     }
+    /**
+     * Retrieve metadata for a file.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<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 (await this.get(filepath)).stat();
     }
+    /**
+     * 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.metadata(filepath)).size;
     }
+    /**
+     * 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.metadata(filepath)).type;
     }
+    /**
+     * 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.metadata(filepath)).lastModified;
     }
+    /**
+     * Retrieve a file from storage.
+     *
+     * @param {string} filepath - The path to the file.
+     * @returns {Promise<Bun.S3File>} The S3 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 this.client.file(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.client.write(filepath, content, options);
@@ -72,10 +139,18 @@ export default class StorageS3Builder {
                 .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.put(destination, await this.get(source), options);
@@ -86,10 +161,18 @@ export default class StorageS3Builder {
                 .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.copy(source, destination, options);
@@ -101,8 +184,14 @@ export default class StorageS3Builder {
                 .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.client.file(filepath).delete();
     }

package/config/storage.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Default storage configuration defining the available disk drivers and their settings.
+ */
 declare const config: Record<string, any>;
 export default config;

package/config/storage.js

@@ -1,17 +1,25 @@
 import App from "@bejibun/app";
 import StorageDiskDriverEnum from "../enums/StorageDiskDriverEnum";
+/**
+ * Default storage configuration defining the available disk drivers and their settings.
+ */
 const config = {
+    /** The default disk used when no disk is specified. */
     default: "local",
+    /** The collection of named storage disks. */
     disks: {
+        /** Local disk using the application storage path as its root. */
         local: {
             driver: StorageDiskDriverEnum.Local,
             root: App.Path.storagePath("app")
         },
+        /** Publicly accessible local disk rooted at the public storage path. */
         public: {
             driver: StorageDiskDriverEnum.Local,
             root: App.Path.storagePath("app/public"),
             url: `${Bun.env.APP_URL}/storage/public`
         },
+        /** S3-compatible disk configured via S3 environment variables. */
         s3: {
             driver: StorageDiskDriverEnum.S3,
             endpoint: Bun.env.S3_ENDPOINT,

package/configure.js

@@ -1,8 +1,13 @@
 import App from "@bejibun/app";
 import Logger from "@bejibun/logger";
 import path from "path";
+/**
+ * Copy all package config files into the application config directory.
+ */
 const configPath = path.resolve(__dirname, "config");
+/** Match JavaScript and TypeScript config file extensions. */
 const regex = /\.(m?js|ts)$/;
+/** The list of config files found in the package config directory. */
 const configs = Array.from(new Bun.Glob("**/*").scanSync({
     cwd: configPath
 })).filter((value) => regex.test(value) && !value.endsWith(".d.ts"));

package/enums/StorageDiskDriverEnum.d.ts

@@ -1,5 +1,10 @@
+/**
+ * Supported storage disk drivers.
+ */
 declare enum StorageDiskDriverEnum {
+    /** Local filesystem disk driver. */
     Local = "local",
+    /** Amazon S3-compatible disk driver. */
     S3 = "s3"
 }
 export default StorageDiskDriverEnum;

package/enums/StorageDiskDriverEnum.js

@@ -1,6 +1,11 @@
+/**
+ * Supported storage disk drivers.
+ */
 var StorageDiskDriverEnum;
 (function (StorageDiskDriverEnum) {
+    /** Local filesystem disk driver. */
     StorageDiskDriverEnum["Local"] = "local";
+    /** Amazon S3-compatible disk driver. */
     StorageDiskDriverEnum["S3"] = "s3";
 })(StorageDiskDriverEnum || (StorageDiskDriverEnum = {}));
 export default StorageDiskDriverEnum;

package/enums/index.d.ts

@@ -1 +1,4 @@
-export * from "../enums/StorageDiskDriverEnum";
+/**
+ * Re-exports the storage enums.
+ */
+export { default as StorageDiskDriverEnum } from "./StorageDiskDriverEnum";

package/enums/index.js

@@ -1 +1,4 @@
-export * from "../enums/StorageDiskDriverEnum";
+/**
+ * Re-exports the storage enums.
+ */
+export { default as StorageDiskDriverEnum } from "./StorageDiskDriverEnum";

package/exceptions/StorageException.d.ts

@@ -1,4 +1,14 @@
+/**
+ * Exception thrown when a storage operation fails.
+ */
 export default class StorageException extends Error {
+    /** The HTTP status code associated with the exception. */
     code: number;
+    /**
+     * Create a new storage exception.
+     *
+     * @param {string} message - The error message.
+     * @param {number} code - The HTTP status code, defaults to 503.
+     */
     constructor(message?: string, code?: number);
 }

package/exceptions/StorageException.js

@@ -1,7 +1,17 @@
 import Logger from "@bejibun/logger";
 import { defineValue } from "@bejibun/utils";
+/**
+ * Exception thrown when a storage operation fails.
+ */
 export default class StorageException extends Error {
+    /** The HTTP status code associated with the exception. */
     code;
+    /**
+     * Create a new storage exception.
+     *
+     * @param {string} message - The error message.
+     * @param {number} code - The HTTP status code, defaults to 503.
+     */
     constructor(message, code) {
         super(message);
         this.name = "StorageException";

package/exceptions/index.d.ts

@@ -1 +1,4 @@
-export * from "../exceptions/StorageException";
+/**
+ * Re-exports the storage exception classes.
+ */
+export { default as StorageException } from "./StorageException";

package/exceptions/index.js

@@ -1 +1,4 @@
-export * from "../exceptions/StorageException";
+/**
+ * Re-exports the storage exception classes.
+ */
+export { default as StorageException } from "./StorageException";