@muhgholy/next-drive 4.6.0 → 4.8.0

package/README.md

@@ -269,18 +269,28 @@ Upload files programmatically from server-side code:
 ```typescript
 import { driveUpload } from "@muhgholy/next-drive/server";
 
-// Upload from file path
+// Upload to specific folder by ID
 const file = await driveUpload(
 	"/tmp/photo.jpg",
 	{ userId: "123" },
 	{
 		name: "photo.jpg",
-		parentId: "folderId", // Optional: folder ID or null for root
+		folder: { id: "folderId" }, // Optional: folder ID
 		accountId: "LOCAL", // Optional: storage account ID
 		enforce: false, // Optional: bypass quota check
 	}
 );
 
+// Upload to folder by path (creates folders if not exist)
+const file = await driveUpload(
+	"/tmp/photo.jpg",
+	{ userId: "123" },
+	{
+		name: "photo.jpg",
+		folder: { path: "images/2024/january" }, // Creates folders recursively
+	}
+);
+
 // Upload from stream
 import fs from "fs";
 const stream = fs.createReadStream("/tmp/video.mp4");
@@ -307,13 +317,14 @@ const file = await driveUpload(
 
 **Options:**
 
-| Option      | Type             | Required | Description                                              |
-| ----------- | ---------------- | -------- | -------------------------------------------------------- |
-| `name`      | `string`         | Yes      | File name with extension                                 |
-| `parentId`  | `string \| null` | No       | Parent folder ID (null or 'root' for root)               |
-| `accountId` | `string`         | No       | Storage account ID ('LOCAL' for local storage)           |
-| `mime`      | `string`         | No       | MIME type (auto-detected from extension if not provided) |
-| `enforce`   | `boolean`        | No       | Bypass quota check (default: false)                      |
+| Option       | Type                              | Required | Description                                              |
+| ------------ | --------------------------------- | -------- | -------------------------------------------------------- |
+| `name`       | `string`                          | Yes      | File name with extension                                 |
+| `folder.id`  | `string`                          | No       | Parent folder ID                                         |
+| `folder.path`| `string`                          | No       | Folder path (e.g., `images/2024`) - creates if not exist |
+| `accountId`  | `string`                          | No       | Storage account ID ('LOCAL' for local storage)           |
+| `mime`       | `string`                          | No       | MIME type (auto-detected from extension if not provided) |
+| `enforce`    | `boolean`                         | No       | Bypass quota check (default: false)                      |
 
 ### Get Signed URL
 
@@ -579,7 +590,7 @@ Serve optimized images with dynamic compression, resizing, and format conversion
 ### URL Format
 
 ```
-/api/drive?action=serve&id={fileId}&quality={preset}&display={context}&size={preset}&format={format}
+/api/drive?action=serve&id={fileId}&quality={preset}&display={context}&size={scale}&format={format}
 ```
 
 ### Parameters
@@ -587,10 +598,22 @@ Serve optimized images with dynamic compression, resizing, and format conversion
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `quality` | `low` / `medium` / `high` / `1-100` | Compression level |
-| `display` | string | Context-based quality adjustment |
-| `size` | string | Predefined dimensions preset |
+| `display` | string | Sets aspect ratio, base dimensions, and quality factor |
+| `size` | string | Scale factor (xs/sm/md/lg/xl) or standalone dimension preset |
 | `format` | `jpeg` / `webp` / `avif` / `png` | Output format |
 
+### How Display + Size Work Together
+
+When **display** is specified, it defines the aspect ratio and base dimensions. The **size** parameter then scales those dimensions:
+
+```
+display=article-image + size=sm  → 400×225  (16:9, half size)
+display=article-image + size=md  → 800×450  (16:9, default)
+display=article-image + size=lg  → 1200×675 (16:9, 1.5x)
+```
+
+When **no display** is specified, size uses standalone presets (fixed dimensions).
+
 ### Quality Presets
 
 | Preset | Base Quality | Use Case |
@@ -602,88 +625,74 @@ Serve optimized images with dynamic compression, resizing, and format conversion
 
 > Quality is dynamically adjusted based on file size. Larger files get more aggressive compression.
 
-### Display Presets (Quality Context)
-
-| Display | Quality Factor | Use Case |
-|---------|----------------|----------|
-| `article-header` | 0.9 | Hero/banner images |
-| `article-image` | 0.85 | In-content images |
-| `thumbnail` | 0.7 | Small previews |
-| `avatar` | 0.8 | Profile pictures |
-| `logo` | 0.95 | Branding/logos |
-| `card` | 0.8 | Card components |
-| `gallery` | 0.85 | Gallery/grid |
-| `og` | 0.9 | Open Graph/social |
-| `icon` | 0.75 | Small icons |
-| `cover` | 0.9 | Full-width covers |
-| `story` | 0.85 | Story/vertical |
-
-### Size Presets (Dimensions)
-
-**Square Sizes:**
-| Size | Dimensions |
-|------|------------|
-| `xs` | 64×64 |
-| `sm` | 128×128 |
-| `md` | 256×256 |
-| `lg` | 512×512 |
-| `xl` | 1024×1024 |
-| `2xl` | 1600×1600 |
-| `icon` | 48×48 |
-| `thumb` | 150×150 |
-| `square` | 600×600 |
-| `avatar-sm` | 64×64 |
-| `avatar-md` | 128×128 |
-| `avatar-lg` | 256×256 |
-
-**Landscape (16:9):**
-| Size | Dimensions |
-|------|------------|
-| `landscape-sm` | 480×270 |
-| `landscape` | 800×450 |
-| `landscape-lg` | 1280×720 |
-| `landscape-xl` | 1920×1080 |
-
-**Portrait (9:16):**
-| Size | Dimensions |
-|------|------------|
-| `portrait-sm` | 270×480 |
-| `portrait` | 450×800 |
-| `portrait-lg` | 720×1280 |
-
-**Wide/Banner:**
-| Size | Dimensions | Ratio |
-|------|------------|-------|
-| `wide` | 1200×630 | OG standard |
-| `banner` | 1200×400 | 3:1 |
-| `banner-sm` | 800×200 | 4:1 |
-
-**Other:**
-| Size | Dimensions | Ratio |
-|------|------------|-------|
-| `photo-4x3` | 800×600 | 4:3 |
-| `photo-3x2` | 900×600 | 3:2 |
-| `story` | 1080×1920 | 9:16 |
-| `video` | 1280×720 | 16:9 |
-| `video-sm` | 640×360 | 16:9 |
-| `card-sm` | 300×200 | 3:2 |
-| `card` | 400×300 | 4:3 |
-| `card-lg` | 600×400 | 3:2 |
+### Display Presets (Aspect Ratio + Dimensions)
+
+| Display | Aspect Ratio | Base Size | Quality Factor |
+|---------|--------------|-----------|----------------|
+| `article-header` | 16:9 | 1200×675 | 0.9 |
+| `article-image` | 16:9 | 800×450 | 0.85 |
+| `thumbnail` | 1:1 | 150×150 | 0.7 |
+| `avatar` | 1:1 | 128×128 | 0.8 |
+| `logo` | 2:1 | 200×100 | 0.95 |
+| `card` | 4:3 | 400×300 | 0.8 |
+| `gallery` | 1:1 | 600×600 | 0.85 |
+| `og` | ~1.9:1 | 1200×630 | 0.9 |
+| `icon` | 1:1 | 48×48 | 0.75 |
+| `cover` | 16:9 | 1920×1080 | 0.9 |
+| `story` | 9:16 | 1080×1920 | 0.85 |
+| `video` | 16:9 | 1280×720 | 0.85 |
+| `banner` | 3:1 | 1200×400 | 0.9 |
+| `portrait` | 3:4 | 600×800 | 0.85 |
+| `landscape` | 4:3 | 800×600 | 0.85 |
+
+### Size Scale (with Display)
+
+When used with a display preset, size scales the dimensions:
+
+| Size | Scale | Example with `article-image` (800×450) |
+|------|-------|----------------------------------------|
+| `xs` | 0.25× | 200×113 |
+| `sm` | 0.5× | 400×225 |
+| `md` | 1.0× | 800×450 |
+| `lg` | 1.5× | 1200×675 |
+| `xl` | 2.0× | 1600×900 |
+| `2xl` | 2.5× | 2000×1125 |
+
+### Standalone Size Presets (without Display)
+
+When no display is specified, use these fixed dimension presets:
+
+| Size | Dimensions | Size | Dimensions |
+|------|------------|------|------------|
+| `xs` | 64×64 | `landscape-sm` | 480×270 |
+| `sm` | 128×128 | `landscape` | 800×450 |
+| `md` | 256×256 | `landscape-lg` | 1280×720 |
+| `lg` | 512×512 | `portrait-sm` | 270×480 |
+| `xl` | 1024×1024 | `portrait` | 450×800 |
+| `icon` | 48×48 | `wide` | 1200×630 |
+| `thumb` | 150×150 | `banner` | 1200×400 |
+| `video` | 1280×720 | `card` | 400×300 |
 
 ### Examples
 
 ```html
-<!-- Article header with OG dimensions -->
-<img src="/api/drive?action=serve&id=123&display=article-header&size=wide&format=webp">
+<!-- Article image, smaller variant (400×225) -->
+<img src="/api/drive?action=serve&id=123&display=article-image&size=sm&format=webp">
+
+<!-- Article image, default size (800×450) -->
+<img src="/api/drive?action=serve&id=123&display=article-image&format=webp">
+
+<!-- Article image, larger variant (1200×675) -->
+<img src="/api/drive?action=serve&id=123&display=article-image&size=lg&format=webp">
 
-<!-- Thumbnail with aggressive compression -->
-<img src="/api/drive?action=serve&id=123&display=thumbnail&size=thumb&format=webp">
+<!-- Thumbnail (150×150 square) -->
+<img src="/api/drive?action=serve&id=123&display=thumbnail&format=webp">
 
-<!-- Avatar -->
-<img src="/api/drive?action=serve&id=123&display=avatar&size=avatar-md&format=webp">
+<!-- Avatar, smaller (64×64) -->
+<img src="/api/drive?action=serve&id=123&display=avatar&size=sm&format=webp">
 
-<!-- Gallery image -->
-<img src="/api/drive?action=serve&id=123&display=gallery&size=landscape&format=webp">
+<!-- Standalone size, no display -->
+<img src="/api/drive?action=serve&id=123&size=landscape&format=webp">
 
 <!-- Just quality, no resize -->
 <img src="/api/drive?action=serve&id=123&quality=medium&format=webp">

package/dist/{chunk-UT2XCOS7.js → chunk-AYHO6FSR.js}

@@ -357,70 +357,58 @@ var extractImageMetadata = async (filePath) => {
   }
 };
 var DISPLAY_PRESETS = {
-  "article-header": 0.9,
-  // Hero/banner images - high quality
-  "article-image": 0.85,
-  // In-content images
-  "thumbnail": 0.7,
-  // Small previews - lower quality ok
-  "avatar": 0.8,
-  // Profile pictures
-  "logo": 0.95,
-  // Branding - needs clarity
-  "card": 0.8,
-  // Card components
-  "gallery": 0.85,
-  // Gallery/grid images
-  "og": 0.9,
-  // Open Graph/social sharing
-  "icon": 0.75,
-  // Small icons
-  "cover": 0.9,
-  // Full-width covers
-  "story": 0.85
-  // Story/vertical format
+  "article-header": { ratio: [16, 9], baseWidth: 1200, qualityFactor: 0.9 },
+  "article-image": { ratio: [16, 9], baseWidth: 800, qualityFactor: 0.85 },
+  "thumbnail": { ratio: [1, 1], baseWidth: 150, qualityFactor: 0.7 },
+  "avatar": { ratio: [1, 1], baseWidth: 128, qualityFactor: 0.8 },
+  "logo": { ratio: [2, 1], baseWidth: 200, qualityFactor: 0.95 },
+  "card": { ratio: [4, 3], baseWidth: 400, qualityFactor: 0.8 },
+  "gallery": { ratio: [1, 1], baseWidth: 600, qualityFactor: 0.85 },
+  "og": { ratio: [1200, 630], baseWidth: 1200, qualityFactor: 0.9 },
+  "icon": { ratio: [1, 1], baseWidth: 48, qualityFactor: 0.75 },
+  "cover": { ratio: [16, 9], baseWidth: 1920, qualityFactor: 0.9 },
+  "story": { ratio: [9, 16], baseWidth: 1080, qualityFactor: 0.85 },
+  "video": { ratio: [16, 9], baseWidth: 1280, qualityFactor: 0.85 },
+  "banner": { ratio: [3, 1], baseWidth: 1200, qualityFactor: 0.9 },
+  "portrait": { ratio: [3, 4], baseWidth: 600, qualityFactor: 0.85 },
+  "landscape": { ratio: [4, 3], baseWidth: 800, qualityFactor: 0.85 }
 };
-var SIZE_PRESETS = {
-  // Square sizes
+var SIZE_SCALES = {
+  "xs": 0.25,
+  "sm": 0.5,
+  "md": 1,
+  "lg": 1.5,
+  "xl": 2,
+  "2xl": 2.5
+};
+var STANDALONE_SIZES = {
   "xs": { width: 64, height: 64 },
   "sm": { width: 128, height: 128 },
   "md": { width: 256, height: 256 },
   "lg": { width: 512, height: 512 },
   "xl": { width: 1024, height: 1024 },
   "2xl": { width: 1600, height: 1600 },
-  // Named squares
   "icon": { width: 48, height: 48 },
   "thumb": { width: 150, height: 150 },
   "square": { width: 600, height: 600 },
   "avatar-sm": { width: 64, height: 64 },
   "avatar-md": { width: 128, height: 128 },
   "avatar-lg": { width: 256, height: 256 },
-  // Landscape (16:9)
   "landscape-sm": { width: 480, height: 270 },
   "landscape": { width: 800, height: 450 },
   "landscape-lg": { width: 1280, height: 720 },
   "landscape-xl": { width: 1920, height: 1080 },
-  // Portrait (9:16)
   "portrait-sm": { width: 270, height: 480 },
   "portrait": { width: 450, height: 800 },
   "portrait-lg": { width: 720, height: 1280 },
-  // Wide/Banner (OG, social)
   "wide": { width: 1200, height: 630 },
-  // Open Graph standard
   "banner": { width: 1200, height: 400 },
-  // Banner/header
   "banner-sm": { width: 800, height: 200 },
-  // Classic photo ratios
   "photo-4x3": { width: 800, height: 600 },
-  // 4:3
   "photo-3x2": { width: 900, height: 600 },
-  // 3:2
-  // Story/vertical (9:16)
   "story": { width: 1080, height: 1920 },
-  // Video thumbnails
   "video": { width: 1280, height: 720 },
   "video-sm": { width: 640, height: 360 },
-  // Card sizes
   "card-sm": { width: 300, height: 200 },
   "card": { width: 400, height: 300 },
   "card-lg": { width: 600, height: 400 }
@@ -434,8 +422,24 @@ var getImageSettings = (fileSizeInBytes, qualityPreset, display, size) => {
     const n = parseInt(qualityPreset, 10);
     if (!isNaN(n)) baseQuality = Math.min(100, Math.max(1, n));
   }
-  const displayFactor = display && DISPLAY_PRESETS[display] ? DISPLAY_PRESETS[display] : 1;
-  baseQuality = Math.round(baseQuality * displayFactor);
+  let width;
+  let height;
+  let qualityFactor = 1;
+  const displayPreset = display ? DISPLAY_PRESETS[display] : void 0;
+  if (displayPreset) {
+    qualityFactor = displayPreset.qualityFactor;
+    const [ratioW, ratioH] = displayPreset.ratio;
+    const scale = size && SIZE_SCALES[size] ? SIZE_SCALES[size] : 1;
+    width = Math.round(displayPreset.baseWidth * scale);
+    height = Math.round(width * ratioH / ratioW);
+  } else if (size) {
+    const standalone = STANDALONE_SIZES[size];
+    if (standalone) {
+      width = standalone.width;
+      height = standalone.height;
+    }
+  }
+  baseQuality = Math.round(baseQuality * qualityFactor);
   let quality = baseQuality;
   let effort = 4;
   let pngCompression = 6;
@@ -463,12 +467,11 @@ var getImageSettings = (fileSizeInBytes, qualityPreset, display, size) => {
       pngCompression = 7;
     }
   }
-  const dimensions = size && SIZE_PRESETS[size] ? SIZE_PRESETS[size] : void 0;
   return {
     quality: Math.max(1, Math.min(100, quality)),
     effort,
     pngCompression,
-    ...dimensions && { width: dimensions.width, height: dimensions.height }
+    ...width && height && { width, height }
   };
 };
 var objectIdSchema = z.string().refine((val) => isValidObjectId(val), {
@@ -1417,6 +1420,46 @@ var driveDelete = async (source, options) => {
   const owner = drive.owner;
   await provider.delete([driveId], owner, accountId);
 };
+var resolveFolderByPath = async (folderPath, owner, accountId) => {
+  const normalizedPath = folderPath.replace(/^\/+|\/+$/g, "");
+  if (!normalizedPath) {
+    throw new Error("Folder path cannot be empty");
+  }
+  const segments = normalizedPath.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    throw new Error("Invalid folder path");
+  }
+  let providerName = "LOCAL";
+  if (accountId && accountId !== "LOCAL") {
+    const account = await drive_default.db.model("StorageAccount").findOne({ _id: accountId, owner });
+    if (!account) {
+      throw new Error("Invalid Storage Account");
+    }
+    if (account.metadata.provider === "GOOGLE") {
+      providerName = "GOOGLE";
+    }
+  }
+  let currentParentId = null;
+  for (const segmentName of segments) {
+    const existingFolder = await drive_default.findOne({
+      owner,
+      "provider.type": providerName,
+      storageAccountId: accountId || null,
+      parentId: currentParentId,
+      name: segmentName,
+      "information.type": "FOLDER",
+      trashedAt: null
+    });
+    if (existingFolder) {
+      currentParentId = String(existingFolder._id);
+    } else {
+      const provider = providerName === "GOOGLE" ? GoogleDriveProvider : LocalStorageProvider;
+      const newFolder = await provider.createFolder(segmentName, currentParentId, owner, accountId);
+      currentParentId = newFolder.id;
+    }
+  }
+  return currentParentId;
+};
 var driveUpload = async (source, key, options) => {
   const config = getDriveConfig();
   let provider = LocalStorageProvider;
@@ -1506,12 +1549,20 @@ var driveUpload = async (source, key, options) => {
         throw new Error("Storage quota exceeded");
       }
     }
+    let resolvedParentId = null;
+    if (options.folder && "path" in options.folder) {
+      resolvedParentId = await resolveFolderByPath(options.folder.path, key, accountId);
+    } else if (options.folder && "id" in options.folder && options.folder.id !== "root") {
+      resolvedParentId = options.folder.id;
+    } else if (options.parentId && options.parentId !== "root") {
+      resolvedParentId = options.parentId;
+    }
     const drive = new drive_default({
       owner: key,
       storageAccountId: accountId || null,
       provider: { type: provider.name },
       name: options.name,
-      parentId: options.parentId === "root" || !options.parentId ? null : options.parentId,
+      parentId: resolvedParentId,
       order: await getNextOrderValue(key),
       information: { type: "FILE", sizeInBytes: fileSize, mime: mimeType, path: "" },
       status: "UPLOADING"
@@ -1672,6 +1723,9 @@ var driveAPIHandler = async (req, res) => {
             const settings = getImageSettings(fileSize, quality, display, sizePreset);
             let targetFormat = format || mime.split("/")[1];
             if (targetFormat === "jpg") targetFormat = "jpeg";
+            if (!["jpeg", "png", "webp", "avif"].includes(targetFormat)) {
+              targetFormat = format || "webp";
+            }
             const cacheDir = path.join(config.storage.path, "file", drive._id.toString(), "cache");
             const cacheKey = [
               "opt",
@@ -1708,13 +1762,17 @@ var driveAPIHandler = async (req, res) => {
               pipeline = pipeline.png({ compressionLevel: settings.pngCompression, adaptiveFiltering: true });
               res.setHeader("Content-Type", "image/png");
             } else if (targetFormat === "webp") {
-              pipeline = pipeline.webp({ quality: settings.quality, effort: settings.effort });
+              const webpEffort = Math.min(settings.effort, 6);
+              pipeline = pipeline.webp({ quality: settings.quality, effort: webpEffort });
               res.setHeader("Content-Type", "image/webp");
             } else if (targetFormat === "avif") {
               pipeline = pipeline.avif({ quality: settings.quality, effort: settings.effort });
               res.setHeader("Content-Type", "image/avif");
             }
             res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+            pipeline.on("error", (err) => {
+              console.error("[next-drive] Pipeline error:", err);
+            });
             stream.pipe(pipeline);
             pipeline.clone().toFile(cachePath).catch((e) => console.error("[next-drive] Cache write failed:", e));
             pipeline.clone().pipe(res);
@@ -2258,5 +2316,5 @@ var driveAPIHandler = async (req, res) => {
 };
 
 export { driveAPIHandler, driveConfiguration, driveDelete, driveFilePath, driveFileSchemaZod, driveGetUrl, driveInfo, driveList, driveReadFile, driveUpload, getDriveConfig, getDriveInformation };
-//# sourceMappingURL=chunk-UT2XCOS7.js.map
-//# sourceMappingURL=chunk-UT2XCOS7.js.map
+//# sourceMappingURL=chunk-AYHO6FSR.js.map
+//# sourceMappingURL=chunk-AYHO6FSR.js.map