@bejibun/storage 0.1.0 → 0.1.11

package/eslint.config.js

@@ -0,0 +1,61 @@
+import js from "@eslint/js";
+import eslintConfigPrettier from "eslint-config-prettier";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+    {
+        ignores: [
+            "node_modules/**",
+            "dist/**",
+            "out/**",
+            "coverage/**",
+            "public/**",
+            "storage/app/**",
+            "storage/cache/**",
+            "storage/framework/**",
+            "bun.lock",
+            "*.tsbuildinfo"
+        ]
+    },
+
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+
+    // All TypeScript (server code + resources/views), no React-specific rules
+    {
+        files: ["**/*.{ts,tsx}"],
+        languageOptions: {
+            ecmaVersion: "latest",
+            sourceType: "module",
+            parserOptions: {
+                ecmaFeatures: {
+                    experimentalDecorators: true
+                }
+            },
+            globals: {
+                ...globals.node,
+                ...globals.browser,
+                Bun: "readonly"
+            }
+        },
+        rules: {
+            "no-unused-vars": "off",
+            "@typescript-eslint/no-unused-vars": [
+                "warn",
+                {
+                    argsIgnorePattern: "^_",
+                    varsIgnorePattern: "^_"
+                }
+            ],
+            "@typescript-eslint/no-explicit-any": "off",
+            "@typescript-eslint/no-empty-object-type": "off",
+            "@typescript-eslint/no-inferrable-types": "off",
+            "@typescript-eslint/no-require-imports": "off",
+            "no-console": "off"
+        }
+    },
+
+    // Prettier must be last: turns off stylistic rules that conflict with formatting
+    eslintConfigPrettier
+);

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";

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);
+        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.0",
+    "version": "0.1.11",
     "author": "Havea Crenata <havea.crenata@gmail.com>",
     "repository": {
         "type": "git",
@@ -8,14 +8,16 @@
     },
     "main": "index.js",
     "module": "index.js",
-    "dependencies": {
-        "@bejibun/app": "^0.1.24",
-        "@bejibun/logger": "^0.1.22",
-        "@bejibun/utils": "^0.1.28"
-    },
     "devDependencies": {
-        "@types/bun": "latest",
-        "tsc-alias": "^1.9.1"
+        "@eslint/js": "^10.0.1",
+        "@types/bun": "^1.4.0",
+        "eslint": "^10.9.1",
+        "eslint-config-prettier": "^10.1.8",
+        "globals": "^17.12.0",
+        "prettier": "^3.9.6",
+        "tsc-alias": "^1.9.4",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.69.0"
     },
     "bugs": {
         "url": "https://github.com/Bejibun-Framework/bejibun-storage/issues"
@@ -31,13 +33,22 @@
     ],
     "license": "MIT",
     "scripts": {
-        "alias": "bunx tsc-alias -p tsconfig.json",
+        "alias": "tsc-alias -p tsconfig.json",
         "types": "cp -rf src/types dist",
         "rsync": "rsync -a dist/ ./",
         "clean": "rm -rf dist",
-        "build": "bunx tsc -p tsconfig.json && bun run types && bun run alias && bun run rsync && bun run clean",
+        "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"
-}
+    "types": "index.d.ts",
+    "dependencies": {
+        "@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);
+    });
+});