@xenterprises/fastify-xstorage 1.0.0

package/src/utils/helpers.js

@@ -0,0 +1,238 @@
+// src/utils/helpers.js
+
+/**
+ * Format file size in human-readable format
+ * @param {number} bytes - File size in bytes
+ * @returns {string}
+ */
+export function formatFileSize(bytes) {
+  if (bytes === 0) return "0 Bytes";
+
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return Math.round((bytes / Math.pow(k, i)) * 100) / 100 + " " + sizes[i];
+}
+
+/**
+ * Generate a unique filename with timestamp
+ * @param {string} originalName - Original filename
+ * @returns {string}
+ */
+export function generateUniqueFilename(originalName) {
+  const timestamp = Date.now();
+  const ext = originalName.substring(originalName.lastIndexOf("."));
+  const name = originalName.substring(0, originalName.lastIndexOf("."));
+  return `${name}-${timestamp}${ext}`;
+}
+
+/**
+ * Validate file type
+ * @param {string} filename - Filename
+ * @param {Array<string>} allowedTypes - Allowed file extensions
+ * @returns {boolean}
+ */
+export function isValidFileType(filename, allowedTypes = []) {
+  if (allowedTypes.length === 0) return true;
+
+  const ext = filename.substring(filename.lastIndexOf(".") + 1).toLowerCase();
+  return allowedTypes.includes(ext);
+}
+
+/**
+ * Check if file is an image
+ * @param {string} filename - Filename
+ * @returns {boolean}
+ */
+export function isImage(filename) {
+  const imageExtensions = ["jpg", "jpeg", "png", "gif", "webp", "svg", "bmp", "avif"];
+  return isValidFileType(filename, imageExtensions);
+}
+
+/**
+ * Check if file is a PDF
+ * @param {string} filename - Filename
+ * @returns {boolean}
+ */
+export function isPdf(filename) {
+  return filename.toLowerCase().endsWith(".pdf");
+}
+
+/**
+ * Check if file is a video
+ * @param {string} filename - Filename
+ * @returns {boolean}
+ */
+export function isVideo(filename) {
+  const videoExtensions = ["mp4", "avi", "mov", "wmv", "flv", "webm", "mkv"];
+  return isValidFileType(filename, videoExtensions);
+}
+
+/**
+ * Sanitize filename to remove unsafe characters
+ * @param {string} filename - Original filename
+ * @returns {string}
+ */
+export function sanitizeFilename(filename) {
+  return filename
+    .replace(/[^a-zA-Z0-9._-]/g, "_") // Replace unsafe chars with underscore
+    .replace(/_{2,}/g, "_") // Replace multiple underscores with single
+    .toLowerCase();
+}
+
+/**
+ * Extract file extension
+ * @param {string} filename - Filename
+ * @returns {string}
+ */
+export function getFileExtension(filename) {
+  return filename.substring(filename.lastIndexOf(".") + 1).toLowerCase();
+}
+
+/**
+ * Get filename without extension
+ * @param {string} filename - Filename
+ * @returns {string}
+ */
+export function getFilenameWithoutExtension(filename) {
+  return filename.substring(0, filename.lastIndexOf("."));
+}
+
+/**
+ * Build storage key with folder structure
+ * @param {string} filename - Filename
+ * @param {object} options - Options
+ * @returns {string}
+ */
+export function buildStorageKey(filename, options = {}) {
+  const { folder = "", prefix = "", suffix = "", timestamp = false } = options;
+
+  let key = filename;
+
+  if (timestamp) {
+    const ext = getFileExtension(filename);
+    const name = getFilenameWithoutExtension(filename);
+    key = `${name}-${Date.now()}.${ext}`;
+  }
+
+  if (prefix) {
+    key = `${prefix}-${key}`;
+  }
+
+  if (suffix) {
+    const ext = getFileExtension(key);
+    const name = getFilenameWithoutExtension(key);
+    key = `${name}-${suffix}.${ext}`;
+  }
+
+  if (folder) {
+    key = `${folder}/${key}`;
+  }
+
+  return key;
+}
+
+/**
+ * Calculate image aspect ratio
+ * @param {number} width - Image width
+ * @param {number} height - Image height
+ * @returns {string}
+ */
+export function getAspectRatio(width, height) {
+  const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
+  const divisor = gcd(width, height);
+  return `${width / divisor}:${height / divisor}`;
+}
+
+/**
+ * Calculate dimensions to fit within max dimensions while preserving aspect ratio
+ * @param {number} width - Original width
+ * @param {number} height - Original height
+ * @param {number} maxWidth - Maximum width
+ * @param {number} maxHeight - Maximum height
+ * @returns {{width: number, height: number}}
+ */
+export function calculateFitDimensions(width, height, maxWidth, maxHeight) {
+  const aspectRatio = width / height;
+
+  let newWidth = width;
+  let newHeight = height;
+
+  if (width > maxWidth) {
+    newWidth = maxWidth;
+    newHeight = newWidth / aspectRatio;
+  }
+
+  if (newHeight > maxHeight) {
+    newHeight = maxHeight;
+    newWidth = newHeight * aspectRatio;
+  }
+
+  return {
+    width: Math.round(newWidth),
+    height: Math.round(newHeight),
+  };
+}
+
+/**
+ * Parse S3 URL to get key
+ * @param {string} url - S3 URL
+ * @param {string} publicUrl - Public URL base
+ * @returns {string}
+ */
+export function getKeyFromUrl(url, publicUrl) {
+  return url.replace(publicUrl + "/", "");
+}
+
+/**
+ * Group files by folder
+ * @param {Array<object>} files - Array of file objects with key property
+ * @returns {object}
+ */
+export function groupFilesByFolder(files) {
+  return files.reduce((acc, file) => {
+    const folder = file.key.includes("/")
+      ? file.key.substring(0, file.key.lastIndexOf("/"))
+      : "root";
+
+    if (!acc[folder]) {
+      acc[folder] = [];
+    }
+
+    acc[folder].push(file);
+    return acc;
+  }, {});
+}
+
+/**
+ * Validate image dimensions
+ * @param {number} width - Image width
+ * @param {number} height - Image height
+ * @param {object} constraints - Dimension constraints
+ * @returns {boolean}
+ */
+export function isValidDimensions(width, height, constraints = {}) {
+  const { minWidth = 0, minHeight = 0, maxWidth = Infinity, maxHeight = Infinity } = constraints;
+
+  return width >= minWidth && width <= maxWidth && height >= minHeight && height <= maxHeight;
+}
+
+/**
+ * Generate responsive image sizes
+ * @param {number} originalWidth - Original image width
+ * @param {number} originalHeight - Original image height
+ * @returns {Array<object>}
+ */
+export function generateResponsiveSizes(originalWidth, originalHeight) {
+  const breakpoints = [320, 640, 768, 1024, 1280, 1536, 1920];
+  const aspectRatio = originalWidth / originalHeight;
+
+  return breakpoints
+    .filter((width) => width <= originalWidth)
+    .map((width) => ({
+      width,
+      height: Math.round(width / aspectRatio),
+      name: `w${width}`,
+    }));
+}

package/src/xStorage.js

@@ -0,0 +1,86 @@
+// src/xStorage.js
+import fp from "fastify-plugin";
+import { S3Client } from "@aws-sdk/client-s3";
+import { getStorageMethods } from "./services/storage.js";
+
+/**
+ * xStorage Plugin for Fastify
+ * Generic S3-compatible file storage library with simple, intuitive API
+ *
+ * Provides methods for:
+ * - Upload, download, delete, list, copy operations
+ * - Signed URLs for secure temporary access (default: private)
+ * - Public URLs for public files (optional)
+ * - Metadata retrieval and file operations
+ * - Concurrent operations (batch uploads/deletes)
+ *
+ * Supports: AWS S3, Cloudflare R2, Digital Ocean Spaces, any S3-compatible provider
+ *
+ * Usage:
+ *   await fastify.xStorage.upload(buffer, 'filename.txt', { folder: 'docs' })
+ *   const url = await fastify.xStorage.getSignedUrl('docs/filename.txt', 3600)
+ *   await fastify.xStorage.delete('docs/filename.txt')
+ *
+ * For specialized processing:
+ * - Use @xenterprises/fastify-ximagepipeline for image processing
+ * - Use your own PDF library or service for PDF operations
+ */
+async function xStoragePlugin(fastify, options) {
+  const {
+    endpoint,
+    region = "us-east-1",
+    accessKeyId,
+    secretAccessKey,
+    bucket,
+    publicUrl,
+    forcePathStyle = true, // Required for Digital Ocean Spaces and some S3-compatible services
+    acl = "private", // Default to private, use signed URLs for access
+  } = options;
+
+  // Validate required options
+  if (!endpoint && !region) {
+    throw new Error("Either endpoint (for S3-compatible) or region (for AWS S3) is required");
+  }
+  if (!accessKeyId || !secretAccessKey) {
+    throw new Error("accessKeyId and secretAccessKey are required");
+  }
+  if (!bucket) {
+    throw new Error("bucket name is required");
+  }
+  if (!publicUrl) {
+    throw new Error("publicUrl is required (e.g., https://your-bucket.nyc3.digitaloceanspaces.com)");
+  }
+
+  console.info("\n 📦 Starting xStorage...\n");
+
+  // Initialize S3 client
+  const s3Client = new S3Client({
+    endpoint,
+    region,
+    credentials: {
+      accessKeyId,
+      secretAccessKey,
+    },
+    forcePathStyle,
+  });
+
+  // Store configuration
+  const config = {
+    s3Client,
+    bucket,
+    publicUrl: publicUrl.endsWith("/") ? publicUrl.slice(0, -1) : publicUrl,
+    acl,
+  };
+
+  // Get storage methods
+  const storageMethods = getStorageMethods(fastify, config);
+
+  // Decorate Fastify with xStorage namespace
+  fastify.decorate("xStorage", storageMethods);
+
+  console.info("\n 📦 xStorage Ready!\n");
+}
+
+export default fp(xStoragePlugin, {
+  name: "xStorage",
+});

package/test/storage.test.js

@@ -0,0 +1,257 @@
+// test/storage.test.js
+import { test } from "node:test";
+import assert from "node:assert";
+import Fastify from "fastify";
+import xStorage from "../src/xStorage.js";
+import { helpers } from "../src/index.js";
+
+// Mock storage configuration
+const mockStorageConfig = {
+  endpoint: process.env.STORAGE_ENDPOINT || "https://nyc3.digitaloceanspaces.com",
+  region: process.env.STORAGE_REGION || "nyc3",
+  accessKeyId: process.env.STORAGE_ACCESS_KEY_ID || "mock_access_key",
+  secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY || "mock_secret_key",
+  bucket: process.env.STORAGE_BUCKET || "test-bucket",
+  publicUrl: process.env.STORAGE_PUBLIC_URL || "https://test-bucket.nyc3.digitaloceanspaces.com",
+};
+
+test("Storage plugin - registers successfully", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+    assert.ok(true, "Plugin registered successfully");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Helper functions - file size formatting", () => {
+  assert.equal(helpers.formatFileSize(0), "0 Bytes");
+  assert.equal(helpers.formatFileSize(1024), "1 KB");
+  assert.equal(helpers.formatFileSize(1048576), "1 MB");
+});
+
+test("Helper functions - file type detection", () => {
+  // isImage
+  assert.equal(helpers.isImage("photo.jpg"), true);
+  assert.equal(helpers.isImage("photo.png"), true);
+  assert.equal(helpers.isImage("photo.webp"), true);
+  assert.equal(helpers.isImage("document.pdf"), false);
+
+  // isPdf
+  assert.equal(helpers.isPdf("document.pdf"), true);
+  assert.equal(helpers.isPdf("photo.jpg"), false);
+
+  // isVideo
+  assert.equal(helpers.isVideo("movie.mp4"), true);
+  assert.equal(helpers.isVideo("photo.jpg"), false);
+});
+
+test("Helper functions - filename sanitization", () => {
+  // Test sanitization - the function replaces special chars with underscore
+  const result1 = helpers.sanitizeFilename("My File (2024).jpg");
+  assert.ok(result1.includes("my_file"), "should contain lowercase filename");
+  assert.ok(result1.endsWith(".jpg"), "should preserve extension");
+
+  const result2 = helpers.sanitizeFilename("Test@#$%.txt");
+  assert.ok(result2.startsWith("test"), "should be lowercase");
+  assert.ok(result2.endsWith(".txt"), "should preserve extension");
+});
+
+test("Helper functions - file extension extraction", () => {
+  assert.equal(helpers.getFileExtension("photo.jpg"), "jpg");
+  assert.equal(helpers.getFileExtension("document.pdf"), "pdf");
+});
+
+test("Helper functions - dimension calculations", () => {
+  const dimensions = helpers.calculateFitDimensions(4000, 3000, 1920, 1080);
+  assert.equal(dimensions.width, 1440);
+  assert.equal(dimensions.height, 1080);
+});
+
+test("Helper functions - aspect ratio calculation", () => {
+  assert.equal(helpers.getAspectRatio(1920, 1080), "16:9");
+  assert.equal(helpers.getAspectRatio(1000, 1000), "1:1");
+});
+
+test("Storage plugin - configuration with custom public URL", async () => {
+  const fastify = Fastify({ logger: false });
+  const customConfig = {
+    ...mockStorageConfig,
+    publicUrl: "https://cdn.example.com",
+  };
+
+  try {
+    await fastify.register(xStorage, customConfig);
+    assert.ok(true, "Plugin registered with custom public URL");
+  } finally {
+    await fastify.close();
+  }
+});
+
+// Generic File Storage Operations Tests
+test("Generic file storage - upload operations available", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+
+    // Verify core storage methods are available
+    assert.ok(fastify.xStorage, "xStorage namespace available");
+    assert.ok(fastify.xStorage.upload, "Upload method exists");
+    assert.ok(fastify.xStorage.download, "Download method exists");
+    assert.ok(fastify.xStorage.delete, "Delete method exists");
+    assert.ok(fastify.xStorage.list, "List method exists");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Generic file storage - file operations", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+
+    // Verify file operations are available
+    assert.ok(fastify.xStorage.copy, "Copy method exists");
+    assert.ok(fastify.xStorage.exists, "Exists check method exists");
+    assert.ok(fastify.xStorage.getMetadata, "Get metadata method exists");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Generic file storage - URL operations", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+
+    // Verify URL operations
+    assert.ok(fastify.xStorage.getSignedUrl, "Signed URL generation available");
+    assert.ok(fastify.xStorage.getPublicUrl, "Public URL generation available");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Error handling - invalid credentials handling", async () => {
+  const fastify = Fastify({ logger: false });
+  const invalidConfig = {
+    ...mockStorageConfig,
+    accessKeyId: "",
+    secretAccessKey: "",
+  };
+
+  try {
+    await assert.rejects(
+      async () => {
+        await fastify.register(xStorage, invalidConfig);
+      },
+      /accessKeyId and secretAccessKey are required/
+    );
+  } finally {
+    try {
+      await fastify.close();
+    } catch {
+      // Ignore
+    }
+  }
+});
+
+test("Batch operations - concurrent uploads", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+
+    // Verify concurrent upload support
+    assert.ok(fastify.xStorage.uploadMultiple, "Concurrent uploads supported");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Batch operations - concurrent deletes", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+
+    // Verify concurrent delete support
+    assert.ok(fastify.xStorage.deleteMultiple, "Concurrent deletes supported");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Edge cases - handle special characters in filename", async () => {
+  const fastify = Fastify({ logger: false });
+
+  try {
+    await fastify.register(xStorage, mockStorageConfig);
+
+    // Special character handling in filenames
+    const result = helpers.sanitizeFilename("Test@#$%^&*()_+=-[]{}|;:,.<>?/~`.jpg");
+    assert.ok(result.endsWith(".jpg"), "Special characters handled");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Configuration - supports AWS S3", async () => {
+  const fastify = Fastify({ logger: false });
+  const awsConfig = {
+    region: "us-east-1",
+    accessKeyId: "mock_key",
+    secretAccessKey: "mock_secret",
+    bucket: "test-bucket",
+    publicUrl: "https://test-bucket.s3.amazonaws.com",
+  };
+
+  try {
+    await fastify.register(xStorage, awsConfig);
+    assert.ok(true, "Plugin supports AWS S3 configuration");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Configuration - supports Cloudflare R2", async () => {
+  const fastify = Fastify({ logger: false });
+  const r2Config = {
+    endpoint: "https://account-id.r2.cloudflarestorage.com",
+    accessKeyId: "mock_key",
+    secretAccessKey: "mock_secret",
+    bucket: "test-bucket",
+    publicUrl: "https://test-bucket.example.com",
+  };
+
+  try {
+    await fastify.register(xStorage, r2Config);
+    assert.ok(true, "Plugin supports Cloudflare R2 configuration");
+  } finally {
+    await fastify.close();
+  }
+});
+
+test("Configuration - supports Digital Ocean Spaces", async () => {
+  const fastify = Fastify({ logger: false });
+  const dosConfig = {
+    endpoint: "https://nyc3.digitaloceanspaces.com",
+    region: "nyc3",
+    accessKeyId: "mock_key",
+    secretAccessKey: "mock_secret",
+    bucket: "test-bucket",
+    publicUrl: "https://test-bucket.nyc3.digitaloceanspaces.com",
+  };
+
+  try {
+    await fastify.register(xStorage, dosConfig);
+    assert.ok(true, "Plugin supports Digital Ocean Spaces configuration");
+  } finally {
+    await fastify.close();
+  }
+});