@bejibun/storage 0.1.1 → 0.1.11

package/facades/Storage.d.ts

@@ -1,18 +1,105 @@
 import type { Stats } from "fs";
 import type { StorageDisk, StorageOptions } from "../types/storage";
 import StorageBuilder from "../builders/StorageBuilder";
+/**
+ * Static facade for performing storage operations via the default builder.
+ */
 export default class Storage {
+    /**
+     * Build a storage builder with the given disk override.
+     *
+     * @param {StorageDisk} disk - The disk configuration to use.
+     * @returns {StorageBuilder} A storage builder bound to the disk.
+     */
     static build(disk: StorageDisk): StorageBuilder;
+    /**
+     * Select a disk by name and return a storage builder.
+     *
+     * @param {string} disk - The name of the disk to use.
+     * @returns {StorageBuilder} A storage builder bound to the disk name.
+     */
     static disk(disk: string): StorageBuilder;
+    /**
+     * Determine whether a file exists.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<boolean>} Whether the file exists.
+     */
     static exists(path: string): Promise<boolean>;
+    /**
+     * Determine whether a file is missing.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<boolean>} Whether the file does not exist.
+     */
     static missing(path: string): Promise<boolean>;
+    /**
+     * Retrieve metadata for a file.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<Stats | Bun.S3Stats>} File metadata and statistics.
+     */
     static metadata(path: string): Promise<Stats | Bun.S3Stats>;
+    /**
+     * Get the file size in bytes.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<number>} The file size in bytes.
+     */
     static size(path: string): Promise<number>;
+    /**
+     * Get the file MIME type.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<string>} The detected MIME type.
+     */
     static mimeType(path: string): Promise<string>;
+    /**
+     * Get the file's last modification date.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<Date>} The last modified timestamp.
+     */
     static lastModified(path: string): Promise<Date>;
+    /**
+     * Retrieve a file from storage.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<Bun.BunFile | Bun.S3File>} The storage file instance.
+     */
     static get(path: string): Promise<Bun.BunFile | Bun.S3File>;
+    /**
+     * Store content at the given path.
+     *
+     * @param {string} path - The destination file path.
+     * @param {any} content - The content to store.
+     * @param {StorageOptions} options - Additional storage options.
+     * @returns {Promise<void>} A promise resolving once the file is stored.
+     */
     static put(path: 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.
+     * @returns {Promise<void>} A promise resolving once the file is copied.
+     */
     static 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.
+     * @returns {Promise<void>} A promise resolving once the file is moved.
+     */
     static move(source: string, destination: string, options?: StorageOptions): Promise<void>;
+    /**
+     * Delete a file from storage.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<void>} A promise resolving once the file is deleted.
+     */
     static delete(path: string): Promise<any>;
 }

package/facades/Storage.js

@@ -1,41 +1,128 @@
 import StorageBuilder from "../builders/StorageBuilder";
+/**
+ * Static facade for performing storage operations via the default builder.
+ */
 export default class Storage {
+    /**
+     * Build a storage builder with the given disk override.
+     *
+     * @param {StorageDisk} disk - The disk configuration to use.
+     * @returns {StorageBuilder} A storage builder bound to the disk.
+     */
     static build(disk) {
         return new StorageBuilder().build(disk);
     }
+    /**
+     * Select a disk by name and return a storage builder.
+     *
+     * @param {string} disk - The name of the disk to use.
+     * @returns {StorageBuilder} A storage builder bound to the disk name.
+     */
     static disk(disk) {
         return new StorageBuilder().disk(disk);
     }
+    /**
+     * Determine whether a file exists.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<boolean>} Whether the file exists.
+     */
     static async exists(path) {
         return await new StorageBuilder().exists(path);
     }
+    /**
+     * Determine whether a file is missing.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<boolean>} Whether the file does not exist.
+     */
     static async missing(path) {
         return await new StorageBuilder().missing(path);
     }
+    /**
+     * Retrieve metadata for a file.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<Stats | Bun.S3Stats>} File metadata and statistics.
+     */
     static async metadata(path) {
         return await new StorageBuilder().metadata(path);
     }
+    /**
+     * Get the file size in bytes.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<number>} The file size in bytes.
+     */
     static async size(path) {
         return await new StorageBuilder().size(path);
     }
+    /**
+     * Get the file MIME type.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<string>} The detected MIME type.
+     */
     static async mimeType(path) {
         return await new StorageBuilder().mimeType(path);
     }
+    /**
+     * Get the file's last modification date.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<Date>} The last modified timestamp.
+     */
     static async lastModified(path) {
         return await new StorageBuilder().lastModified(path);
     }
+    /**
+     * Retrieve a file from storage.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<Bun.BunFile | Bun.S3File>} The storage file instance.
+     */
     static async get(path) {
         return await new StorageBuilder().get(path);
     }
+    /**
+     * Store content at the given path.
+     *
+     * @param {string} path - The destination file path.
+     * @param {any} content - The content to store.
+     * @param {StorageOptions} options - Additional storage options.
+     * @returns {Promise<void>} A promise resolving once the file is stored.
+     */
     static async put(path, content, options) {
         return await new StorageBuilder().put(path, content, options);
     }
+    /**
+     * 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.
+     * @returns {Promise<void>} A promise resolving once the file is copied.
+     */
     static async copy(source, destination, options) {
         return await new StorageBuilder().copy(source, destination, options);
     }
+    /**
+     * 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.
+     * @returns {Promise<void>} A promise resolving once the file is moved.
+     */
     static async move(source, destination, options) {
         return await new StorageBuilder().move(source, destination, options);
     }
+    /**
+     * Delete a file from storage.
+     *
+     * @param {string} path - The path to the file.
+     * @returns {Promise<void>} A promise resolving once the file is deleted.
+     */
     static async delete(path) {
         return await new StorageBuilder().delete(path);
     }

package/facades/index.d.ts

@@ -1 +1,4 @@
-export * from "../facades/Storage";
+/**
+ * Re-exports the Storage facade.
+ */
+export { default as Storage } from "./Storage";

package/facades/index.js

@@ -1 +1,4 @@
-export * from "../facades/Storage";
+/**
+ * Re-exports the Storage facade.
+ */
+export { default as Storage } from "./Storage";

package/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Re-exports the Storage facade, storage enums, exception classes, and facade barrel as the package entry point.
+ */
 export { default } from "./facades/Storage";
 export * from "./enums/index";
+export * from "./exceptions/index";
 export * from "./facades/index";

package/index.js

@@ -1,3 +1,7 @@
+/**
+ * Re-exports the Storage facade, storage enums, exception classes, and facade barrel as the package entry point.
+ */
 export { default } from "./facades/Storage";
 export * from "./enums/index";
+export * from "./exceptions/index";
 export * from "./facades/index";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bejibun/storage",
-    "version": "0.1.1",
+    "version": "0.1.11",
     "author": "Havea Crenata <havea.crenata@gmail.com>",
     "repository": {
         "type": "git",
@@ -10,14 +10,14 @@
     "module": "index.js",
     "devDependencies": {
         "@eslint/js": "^10.0.1",
-        "@types/bun": "^1.3.14",
-        "eslint": "^10.8.1",
+        "@types/bun": "^1.4.0",
+        "eslint": "^10.9.1",
         "eslint-config-prettier": "^10.1.8",
-        "globals": "^17.11.0",
+        "globals": "^17.12.0",
         "prettier": "^3.9.6",
-        "tsc-alias": "^1.9.2",
+        "tsc-alias": "^1.9.4",
         "typescript": "^6.0.3",
-        "typescript-eslint": "^8.67.0"
+        "typescript-eslint": "^8.69.0"
     },
     "bugs": {
         "url": "https://github.com/Bejibun-Framework/bejibun-storage/issues"
@@ -40,14 +40,15 @@
         "format": "prettier --write src --log-level=silent",
         "eslint": "eslint src",
         "lint": "bun run format && bun run eslint",
+        "test": "bun test tests/",
         "build": "bun run lint && tsc -p tsconfig.json && bun run types && bun run alias && bun run rsync && bun run clean",
         "deploy": "bun run build && bun publish --access public"
     },
     "type": "module",
     "types": "index.d.ts",
     "dependencies": {
-        "@bejibun/app": "^0.1.25",
-        "@bejibun/logger": "^0.1.23",
-        "@bejibun/utils": "^0.1.29"
+        "@bejibun/app": "^0.1.26",
+        "@bejibun/logger": "^0.2.1",
+        "@bejibun/utils": "^0.1.30"
     }
 }

package/tests/integration/storage.integration.test.ts

@@ -0,0 +1,145 @@
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    beforeEach,
+    describe,
+    expect,
+    mock,
+    test
+} from "bun:test";
+import StorageBuilder from "../../src/builders/StorageBuilder";
+import Storage from "../../src/facades/Storage";
+
+const rootDir = `${process.env.TMPDIR ?? "/tmp"}/bejibun-storage-int-${Date.now()}`;
+const disk = {driver: "local", root: rootDir};
+
+let writtenFiles: Array<string> = [];
+
+const log = mock(console.log);
+const error = mock(console.error);
+
+beforeAll(async () => {
+    await Bun.write(`${rootDir}/.keep`, "");
+});
+
+beforeEach(() => {
+    log.mockReset();
+    error.mockReset();
+    console.log = log;
+    console.error = error;
+    writtenFiles = [];
+});
+
+afterEach(() => {
+    console.log = console.log;
+    console.error = console.error;
+    void cleanup();
+});
+
+async function cleanup() {
+    for (const file of writtenFiles) {
+        try {
+            if (await Bun.file(file).exists()) await Bun.file(file).delete();
+        } catch {
+            /* already removed by the test */
+        }
+    }
+    writtenFiles = [];
+}
+
+afterAll(async () => {
+    await Bun.file(`${rootDir}/.keep`).delete();
+});
+
+describe("StorageBuilder integration (local disk)", () => {
+    test("put stores content and exists/size read it back", async () => {
+        const builder = new StorageBuilder().build(disk);
+        const filepath = `${rootDir}/hello.txt`;
+
+        writtenFiles.push(filepath);
+
+        await builder.put(filepath, "hello world");
+
+        expect(await builder.exists(filepath)).toBe(true);
+        expect(await builder.missing(filepath)).toBe(false);
+        expect(await builder.size(filepath)).toBe(11);
+        expect(await (await builder.get(filepath)).text()).toBe("hello world");
+    });
+
+    test("metadata and lastModified are available after a write", async () => {
+        const builder = new StorageBuilder().build(disk);
+        const filepath = `${rootDir}/meta.txt`;
+
+        writtenFiles.push(filepath);
+
+        await builder.put(filepath, "meta");
+
+        const meta = await builder.metadata(filepath);
+
+        expect(meta.size).toBe(4);
+        expect(await builder.lastModified(filepath)).toBeInstanceOf(Date);
+        expect(builder.mimeType(filepath)).toBeTruthy();
+    });
+
+    test("copy duplicates the file", async () => {
+        const builder = new StorageBuilder().build(disk);
+        const source = `${rootDir}/copy-src.txt`;
+        const destination = `${rootDir}/copy-dst.txt`;
+
+        writtenFiles.push(source, destination);
+
+        await builder.put(source, "copy me");
+        await builder.copy(source, destination);
+
+        expect(await builder.exists(destination)).toBe(true);
+        expect(await (await builder.get(destination)).text()).toBe("copy me");
+    });
+
+    test("move relocates the file and removes the source", async () => {
+        const builder = new StorageBuilder().build(disk);
+        const source = `${rootDir}/move-src.txt`;
+        const destination = `${rootDir}/move-dst.txt`;
+
+        writtenFiles.push(source, destination);
+
+        await builder.put(source, "move me");
+        await builder.move(source, destination);
+
+        expect(await builder.exists(source)).toBe(false);
+        expect(await builder.exists(destination)).toBe(true);
+        expect(await (await builder.get(destination)).text()).toBe("move me");
+    });
+
+    test("delete removes the file", async () => {
+        const builder = new StorageBuilder().build(disk);
+        const filepath = `${rootDir}/delete.txt`;
+
+        writtenFiles.push(filepath);
+
+        await builder.put(filepath, "gone");
+        await builder.delete(filepath);
+
+        expect(await builder.exists(filepath)).toBe(false);
+        expect(await builder.missing(filepath)).toBe(true);
+    });
+});
+
+describe("Storage facade integration (local disk)", () => {
+    test("disk + build resolve the same local disk", async () => {
+        const builder = Storage.build(disk).disk("local");
+
+        expect(builder).toBeInstanceOf(StorageBuilder);
+    });
+
+    test("put via facade stores and get reads back relative to the disk root", async () => {
+        const builder = new StorageBuilder().build(disk);
+        const filepath = `${rootDir}/facade-put.txt`;
+
+        writtenFiles.push(filepath);
+
+        await builder.put(filepath, "facade");
+
+        expect(await builder.exists(filepath)).toBe(true);
+    });
+});

package/tests/unit/storage.test.ts

@@ -0,0 +1,177 @@
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    mock,
+    test
+} from "bun:test";
+import StorageBuilder from "../../src/builders/StorageBuilder";
+import StorageException from "../../src/exceptions/StorageException";
+import Storage from "../../src/facades/Storage";
+
+const log = mock(console.log);
+const error = mock(console.error);
+
+beforeEach(() => {
+    log.mockReset();
+    error.mockReset();
+    console.log = log;
+    console.error = error;
+});
+
+afterEach(() => {
+    console.log = console.log;
+    console.error = console.error;
+});
+
+describe("StorageBuilder", () => {
+    test("build applies the disk override and returns the builder", () => {
+        const disk = {driver: "local", root: "/tmp"};
+        const builder = new StorageBuilder().build(disk);
+
+        expect(builder).toBeInstanceOf(StorageBuilder);
+    });
+
+    test("disk selects a disk by name and returns the builder", () => {
+        const builder = new StorageBuilder().disk("local");
+
+        expect(builder).toBeInstanceOf(StorageBuilder);
+    });
+
+    test("exists throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.exists("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("missing throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.missing("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("metadata throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.metadata("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("size throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.size("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("mimeType throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.mimeType("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("lastModified throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.lastModified("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("get throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.get("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("put throws when the file path or content is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const pathError: any = await builder.put("", "x").catch((e) => e);
+
+        expect(pathError).toBeInstanceOf(StorageException);
+        expect(pathError.message).toBe("The file path is required.");
+
+        const contentError: any = await builder.put("file.txt", "").catch((e) => e);
+
+        expect(contentError).toBeInstanceOf(StorageException);
+        expect(contentError.message).toBe("The content is required.");
+    });
+
+    test("copy throws when the source or destination path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const sourceError: any = await builder.copy("", "dst").catch((e) => e);
+
+        expect(sourceError.message).toBe("The source file path is required.");
+
+        const destError: any = await builder.copy("src", "").catch((e) => e);
+
+        expect(destError.message).toBe("The destination file path is required.");
+    });
+
+    test("move throws when the source or destination path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const sourceError: any = await builder.move("", "dst").catch((e) => e);
+
+        expect(sourceError.message).toBe("The source file path is required.");
+
+        const destError: any = await builder.move("src", "").catch((e) => e);
+
+        expect(destError.message).toBe("The destination file path is required.");
+    });
+
+    test("delete throws when the file path is empty", async () => {
+        const builder = new StorageBuilder();
+
+        const error: any = await builder.delete("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+});
+
+describe("Storage facade", () => {
+    test("build returns a StorageBuilder", () => {
+        expect(Storage.build({driver: "local", root: "/tmp"})).toBeInstanceOf(
+            StorageBuilder
+        );
+    });
+
+    test("disk returns a StorageBuilder", () => {
+        expect(Storage.disk("local")).toBeInstanceOf(StorageBuilder);
+    });
+
+    test("exists throws when the file path is empty", async () => {
+        const error: any = await Storage.exists("").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+
+    test("put throws when the file path is empty", async () => {
+        const error: any = await Storage.put("", "x").catch((e) => e);
+
+        expect(error).toBeInstanceOf(StorageException);
+        expect(error.message).toBe("The file path is required.");
+    });
+});

package/tsconfig.json

@@ -13,5 +13,6 @@
             "@/*": ["./src/*"]
         },
         "types": ["bun-types"]
-    }
+    },
+    "exclude": ["tests"]
 }

package/types/index.d.ts

@@ -1 +1,4 @@
-export * from "../types/storage";
+/**
+ * Re-exports the storage type declarations.
+ */
+export * from "./storage";