@muhgholy/next-drive 4.7.0 → 4.9.0

package/README.md

@@ -590,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}&fit={mode}&position={anchor}&format={format}
 ```
 
 ### Parameters
@@ -598,10 +598,46 @@ 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, quality factor, and default fit |
+| `size` | string | Scale factor (xs/sm/md/lg/xl) or standalone dimension preset |
+| `fit` | `cover` / `contain` / `fill` / `inside` / `outside` | How image fits into dimensions |
+| `position` | `center` / `top` / `bottom` / `left` / `right` / `attention` / `entropy` | Crop anchor point (for cover/contain) |
 | `format` | `jpeg` / `webp` / `avif` / `png` | Output format |
 
+### Fit Options
+
+| Fit | Behavior | Use Case |
+|-----|----------|----------|
+| `cover` | Crop to fill exact dimensions | Thumbnails, avatars, cards |
+| `contain` | Fit within dimensions (may letterbox) | Logos, icons |
+| `fill` | Stretch to exact dimensions (may distort) | Background fills |
+| `inside` | Fit within, no upscaling *(default)* | Article images |
+| `outside` | Cover minimum dimensions | Backgrounds |
+
+### Position Options (for cover/contain)
+
+| Position | Anchor Point |
+|----------|--------------|
+| `center` | Center *(default)* |
+| `top` | Top center |
+| `bottom` | Bottom center |
+| `left` | Left center |
+| `right` | Right center |
+| `attention` | Focus on most "interesting" area (AI-based) |
+| `entropy` | Focus on highest entropy area |
+
+### How Display + Size Work Together
+
+When **display** is specified, it defines the aspect ratio, base dimensions, and default fit. The **size** parameter then scales those dimensions:
+
+```
+display=article-image + size=sm  → 400×225  (16:9, half size, fit=inside)
+display=thumbnail + size=md     → 150×150  (1:1, fit=cover)
+display=avatar + fit=contain    → 128×128  (override default cover to contain)
+```
+
+When **no display** is specified, size uses standalone presets (fixed dimensions).
+
 ### Quality Presets
 
 | Preset | Base Quality | Use Case |
@@ -613,88 +649,77 @@ 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 + Fit)
+
+| Display | Aspect Ratio | Base Size | Quality | Default Fit |
+|---------|--------------|-----------|---------|-------------|
+| `article-header` | 16:9 | 1200×675 | 0.9 | inside |
+| `article-image` | 16:9 | 800×450 | 0.85 | inside |
+| `thumbnail` | 1:1 | 150×150 | 0.7 | cover |
+| `avatar` | 1:1 | 128×128 | 0.8 | cover |
+| `logo` | 2:1 | 200×100 | 0.95 | contain |
+| `card` | 4:3 | 400×300 | 0.8 | cover |
+| `gallery` | 1:1 | 600×600 | 0.85 | cover |
+| `og` | ~1.9:1 | 1200×630 | 0.9 | cover |
+| `icon` | 1:1 | 48×48 | 0.75 | cover |
+| `cover` | 16:9 | 1920×1080 | 0.9 | cover |
+| `story` | 9:16 | 1080×1920 | 0.85 | cover |
+| `video` | 16:9 | 1280×720 | 0.85 | cover |
+| `banner` | 3:1 | 1200×400 | 0.9 | cover |
+| `portrait` | 3:4 | 600×800 | 0.85 | inside |
+| `landscape` | 4:3 | 800×600 | 0.85 | inside |
+
+### 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, fit=inside) -->
+<img src="/api/drive?action=serve&id=123&display=article-image&size=sm&format=webp">
+
+<!-- Thumbnail with cover fit (crops to fill 150×150 square) -->
+<img src="/api/drive?action=serve&id=123&display=thumbnail&format=webp">
+
+<!-- Avatar with top-focused crop (for face photos) -->
+<img src="/api/drive?action=serve&id=123&display=avatar&fit=cover&position=top&format=webp">
+
+<!-- Gallery with AI-based attention crop -->
+<img src="/api/drive?action=serve&id=123&display=gallery&fit=cover&position=attention&format=webp">
 
-<!-- Thumbnail with aggressive compression -->
-<img src="/api/drive?action=serve&id=123&display=thumbnail&size=thumb&format=webp">
+<!-- Card image, override default cover to contain -->
+<img src="/api/drive?action=serve&id=123&display=card&fit=contain&format=webp">
 
-<!-- Avatar -->
-<img src="/api/drive?action=serve&id=123&display=avatar&size=avatar-md&format=webp">
+<!-- Banner with custom position -->
+<img src="/api/drive?action=serve&id=123&display=banner&position=bottom&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&fit=cover&format=webp">
 
 <!-- Just quality, no resize -->
 <img src="/api/drive?action=serve&id=123&quality=medium&format=webp">

package/dist/{chunk-OWKTTRQC.js → chunk-C5CORNPP.js}

@@ -357,75 +357,77 @@ 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, defaultFit: "inside" },
+  "article-image": { ratio: [16, 9], baseWidth: 800, qualityFactor: 0.85, defaultFit: "inside" },
+  "thumbnail": { ratio: [1, 1], baseWidth: 150, qualityFactor: 0.7, defaultFit: "cover" },
+  "avatar": { ratio: [1, 1], baseWidth: 128, qualityFactor: 0.8, defaultFit: "cover" },
+  "logo": { ratio: [2, 1], baseWidth: 200, qualityFactor: 0.95, defaultFit: "contain" },
+  "card": { ratio: [4, 3], baseWidth: 400, qualityFactor: 0.8, defaultFit: "cover" },
+  "gallery": { ratio: [1, 1], baseWidth: 600, qualityFactor: 0.85, defaultFit: "cover" },
+  "og": { ratio: [1200, 630], baseWidth: 1200, qualityFactor: 0.9, defaultFit: "cover" },
+  "icon": { ratio: [1, 1], baseWidth: 48, qualityFactor: 0.75, defaultFit: "cover" },
+  "cover": { ratio: [16, 9], baseWidth: 1920, qualityFactor: 0.9, defaultFit: "cover" },
+  "story": { ratio: [9, 16], baseWidth: 1080, qualityFactor: 0.85, defaultFit: "cover" },
+  "video": { ratio: [16, 9], baseWidth: 1280, qualityFactor: 0.85, defaultFit: "cover" },
+  "banner": { ratio: [3, 1], baseWidth: 1200, qualityFactor: 0.9, defaultFit: "cover" },
+  "portrait": { ratio: [3, 4], baseWidth: 600, qualityFactor: 0.85, defaultFit: "inside" },
+  "landscape": { ratio: [4, 3], baseWidth: 800, qualityFactor: 0.85, defaultFit: "inside" }
 };
-var SIZE_PRESETS = {
-  // Square sizes
+var VALID_FIT_OPTIONS = ["cover", "contain", "fill", "inside", "outside"];
+var VALID_POSITION_OPTIONS = [
+  "center",
+  "top",
+  "right top",
+  "right",
+  "right bottom",
+  "bottom",
+  "left bottom",
+  "left",
+  "left top",
+  "attention",
+  "entropy"
+];
+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 }
 };
-var getImageSettings = (fileSizeInBytes, qualityPreset, display, size) => {
+var getImageSettings = (fileSizeInBytes, qualityPreset, display, size, fit, position) => {
   let baseQuality = 80;
   if (qualityPreset === "low") baseQuality = 30;
   else if (qualityPreset === "medium") baseQuality = 50;
@@ -434,8 +436,28 @@ 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;
+  let defaultFit = "inside";
+  const displayPreset = display ? DISPLAY_PRESETS[display] : void 0;
+  if (displayPreset) {
+    qualityFactor = displayPreset.qualityFactor;
+    defaultFit = displayPreset.defaultFit;
+    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;
+    }
+  }
+  const resolvedFit = fit && VALID_FIT_OPTIONS.includes(fit) ? fit : defaultFit;
+  const resolvedPosition = position && VALID_POSITION_OPTIONS.includes(position) ? position : void 0;
+  baseQuality = Math.round(baseQuality * qualityFactor);
   let quality = baseQuality;
   let effort = 4;
   let pngCompression = 6;
@@ -463,12 +485,12 @@ 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, fit: resolvedFit },
+    ...resolvedPosition && { position: resolvedPosition }
   };
 };
 var objectIdSchema = z.string().refine((val) => isValidObjectId(val), {
@@ -1547,9 +1569,9 @@ var driveUpload = async (source, key, options) => {
       }
     }
     let resolvedParentId = null;
-    if (options.folder?.path) {
+    if (options.folder && "path" in options.folder) {
       resolvedParentId = await resolveFolderByPath(options.folder.path, key, accountId);
-    } else if (options.folder?.id && options.folder.id !== "root") {
+    } 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;
@@ -1709,23 +1731,30 @@ var driveAPIHandler = async (req, res) => {
         const quality = req.query.quality;
         const display = req.query.display;
         const sizePreset = req.query.size;
+        const fit = req.query.fit;
+        const position = req.query.position;
         const isImage = mime.startsWith("image/");
-        const shouldTransform = isImage && (format || quality || display || sizePreset);
+        const shouldTransform = isImage && (format || quality || display || sizePreset || fit);
         res.setHeader("Content-Disposition", `inline; filename="${safeFilename}"`);
         if (config.cors?.enabled) {
           res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
         }
         if (shouldTransform) {
           try {
-            const settings = getImageSettings(fileSize, quality, display, sizePreset);
+            const settings = getImageSettings(fileSize, quality, display, sizePreset, fit, position);
             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",
               `q${settings.quality}`,
               `e${settings.effort}`,
               settings.width ? `${settings.width}x${settings.height}` : "orig",
+              settings.fit || "none",
+              settings.position || "c",
               targetFormat
             ].join("_");
             const cachePath = path.join(cacheDir, `${cacheKey}.bin`);
@@ -1745,7 +1774,8 @@ var driveAPIHandler = async (req, res) => {
             let pipeline = sharp();
             if (settings.width && settings.height) {
               pipeline = pipeline.resize(settings.width, settings.height, {
-                fit: "inside",
+                fit: settings.fit || "inside",
+                position: settings.position || "center",
                 withoutEnlargement: true
               });
             }
@@ -1756,13 +1786,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);
@@ -2306,5 +2340,5 @@ var driveAPIHandler = async (req, res) => {
 };
 
 export { driveAPIHandler, driveConfiguration, driveDelete, driveFilePath, driveFileSchemaZod, driveGetUrl, driveInfo, driveList, driveReadFile, driveUpload, getDriveConfig, getDriveInformation };
-//# sourceMappingURL=chunk-OWKTTRQC.js.map
-//# sourceMappingURL=chunk-OWKTTRQC.js.map
+//# sourceMappingURL=chunk-C5CORNPP.js.map
+//# sourceMappingURL=chunk-C5CORNPP.js.map