@muhgholy/next-drive 4.4.0 → 4.6.0

package/README.md

@@ -55,17 +55,6 @@ This package uses [subpath exports](https://nodejs.org/api/packages.html#subpath
 }
 ```
 
-**For projects using bundlers (Vite, Webpack, etc.):**
-
-```json
-{
-	"compilerOptions": {
-		"module": "esnext",
-		"moduleResolution": "bundler"
-	}
-}
-```
-
 > ⚠️ The legacy `"moduleResolution": "node"` is **not supported** and will cause build errors with subpath imports like `@muhgholy/next-drive/server`.
 
 **FFmpeg** (for video thumbnails):
@@ -583,25 +572,122 @@ GOOGLE_REDIRECT_URI=http://localhost:3000/api/drive?action=callback
 
 ---
 
-## API Endpoints
-
-All operations use `?action=` query parameter:
-
-| Action            | Method | Description          |
-| ----------------- | ------ | -------------------- |
-| `upload`          | POST   | Chunked file upload  |
-| `list`            | GET    | List folder contents |
-| `serve`           | GET    | Serve file content   |
-| `thumbnail`       | GET    | Get file thumbnail   |
-| `rename`          | PATCH  | Rename file/folder   |
-| `trash`           | POST   | Move to trash        |
-| `deletePermanent` | DELETE | Delete permanently   |
-| `restore`         | POST   | Restore from trash   |
-| `emptyTrash`      | DELETE | Empty all trash      |
-| `createFolder`    | POST   | Create folder        |
-| `move`            | POST   | Move to new parent   |
-| `search`          | GET    | Search by name       |
-| `quota`           | GET    | Get storage usage    |
+## Image Optimization
+
+Serve optimized images with dynamic compression, resizing, and format conversion using query parameters.
+
+### URL Format
+
+```
+/api/drive?action=serve&id={fileId}&quality={preset}&display={context}&size={preset}&format={format}
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `quality` | `low` / `medium` / `high` / `1-100` | Compression level |
+| `display` | string | Context-based quality adjustment |
+| `size` | string | Predefined dimensions preset |
+| `format` | `jpeg` / `webp` / `avif` / `png` | Output format |
+
+### Quality Presets
+
+| Preset | Base Quality | Use Case |
+|--------|--------------|----------|
+| `low` | 30 | Thumbnails, previews |
+| `medium` | 50 | General content |
+| `high` | 75 | High-quality display |
+| `1-100` | Custom | Fine-tuned control |
+
+> 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 |
+
+### Examples
+
+```html
+<!-- Article header with OG dimensions -->
+<img src="/api/drive?action=serve&id=123&display=article-header&size=wide&format=webp">
+
+<!-- Thumbnail with aggressive compression -->
+<img src="/api/drive?action=serve&id=123&display=thumbnail&size=thumb&format=webp">
+
+<!-- Avatar -->
+<img src="/api/drive?action=serve&id=123&display=avatar&size=avatar-md&format=webp">
+
+<!-- Gallery image -->
+<img src="/api/drive?action=serve&id=123&display=gallery&size=landscape&format=webp">
+
+<!-- Just quality, no resize -->
+<img src="/api/drive?action=serve&id=123&quality=medium&format=webp">
+```
 
 ---
 

package/dist/{chunk-ZNXH3LYN.cjs → chunk-I3AR7V7Z.cjs}

@@ -369,6 +369,121 @@ var extractImageMetadata = async (filePath) => {
     return null;
   }
 };
+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
+};
+var SIZE_PRESETS = {
+  // Square 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) => {
+  let baseQuality = 80;
+  if (qualityPreset === "low") baseQuality = 30;
+  else if (qualityPreset === "medium") baseQuality = 50;
+  else if (qualityPreset === "high") baseQuality = 75;
+  else if (qualityPreset) {
+    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 quality = baseQuality;
+  let effort = 4;
+  let pngCompression = 6;
+  if (fileSizeInBytes) {
+    const sizeInKB = fileSizeInBytes / 1024;
+    if (sizeInKB > 500) {
+      quality = Math.min(baseQuality, 25);
+      effort = 9;
+      pngCompression = 9;
+    } else if (sizeInKB > 300) {
+      quality = Math.min(baseQuality, 30);
+      effort = 8;
+      pngCompression = 9;
+    } else if (sizeInKB > 150) {
+      quality = Math.min(baseQuality, 35);
+      effort = 7;
+      pngCompression = 8;
+    } else if (sizeInKB > 90) {
+      quality = Math.min(baseQuality, 40);
+      effort = 6;
+      pngCompression = 8;
+    } else if (sizeInKB > 50) {
+      quality = Math.min(baseQuality, 50);
+      effort = 5;
+      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 }
+  };
+};
 var objectIdSchema = zod.z.string().refine((val) => mongoose.isValidObjectId(val), {
   message: "Invalid ObjectId format"
 });
@@ -1553,14 +1668,76 @@ var driveAPIHandler = async (req, res) => {
         return;
       }
       if (action === "serve") {
-        const { stream, mime, size } = await itemProvider.openStream(drive, itemAccountId);
+        const { stream, mime, size: fileSize } = await itemProvider.openStream(drive, itemAccountId);
         const safeFilename = sanitizeContentDispositionFilename(drive.name);
+        const format = req.query.format;
+        const quality = req.query.quality;
+        const display = req.query.display;
+        const sizePreset = req.query.size;
+        const isImage = mime.startsWith("image/");
+        const shouldTransform = isImage && (format || quality || display || sizePreset);
         res.setHeader("Content-Disposition", `inline; filename="${safeFilename}"`);
-        res.setHeader("Content-Type", mime);
         if (config.cors?.enabled) {
           res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
         }
-        if (size) res.setHeader("Content-Length", size);
+        if (shouldTransform) {
+          try {
+            const settings = getImageSettings(fileSize, quality, display, sizePreset);
+            let targetFormat = format || mime.split("/")[1];
+            if (targetFormat === "jpg") targetFormat = "jpeg";
+            const cacheDir = path__default.default.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",
+              targetFormat
+            ].join("_");
+            const cachePath = path__default.default.join(cacheDir, `${cacheKey}.bin`);
+            if (fs__default.default.existsSync(cachePath)) {
+              const cacheStat = fs__default.default.statSync(cachePath);
+              res.setHeader("Content-Type", `image/${targetFormat}`);
+              res.setHeader("Content-Length", cacheStat.size);
+              res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+              if (config.cors?.enabled) {
+                res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
+              }
+              if ("destroy" in stream) stream.destroy();
+              fs__default.default.createReadStream(cachePath).pipe(res);
+              return;
+            }
+            if (!fs__default.default.existsSync(cacheDir)) fs__default.default.mkdirSync(cacheDir, { recursive: true });
+            let pipeline = sharp__default.default();
+            if (settings.width && settings.height) {
+              pipeline = pipeline.resize(settings.width, settings.height, {
+                fit: "inside",
+                withoutEnlargement: true
+              });
+            }
+            if (targetFormat === "jpeg") {
+              pipeline = pipeline.jpeg({ quality: settings.quality, mozjpeg: true });
+              res.setHeader("Content-Type", "image/jpeg");
+            } else if (targetFormat === "png") {
+              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 });
+              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");
+            stream.pipe(pipeline);
+            pipeline.clone().toFile(cachePath).catch((e) => console.error("[next-drive] Cache write failed:", e));
+            pipeline.clone().pipe(res);
+            return;
+          } catch (e) {
+            console.error("[next-drive] Image transformation failed:", e);
+          }
+        }
+        res.setHeader("Content-Type", mime);
+        if (fileSize) res.setHeader("Content-Length", fileSize);
         stream.pipe(res);
         return;
       }
@@ -2105,5 +2282,5 @@ exports.driveReadFile = driveReadFile;
 exports.driveUpload = driveUpload;
 exports.getDriveConfig = getDriveConfig;
 exports.getDriveInformation = getDriveInformation;
-//# sourceMappingURL=chunk-ZNXH3LYN.cjs.map
-//# sourceMappingURL=chunk-ZNXH3LYN.cjs.map
+//# sourceMappingURL=chunk-I3AR7V7Z.cjs.map
+//# sourceMappingURL=chunk-I3AR7V7Z.cjs.map