nuxt-filer 0.0.8 → 0.0.11

package/README.md

@@ -16,6 +16,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 - **Auto-imported** — `useFileStorage()`, types, and provider utilities are auto-imported in server context
 - **Group-based organization** — files are organized by `groupId` (project, ticket, order, etc.)
 - **`@nuxt/image` integration** — when `@nuxt/image` is installed, an IPX endpoint is wired up automatically so `<NuxtImg provider="filer" src="<groupId>/<id>" />` returns optimized variants of stored files
+- **Upload-time image processing** — optionally run images through Sharp when storing them (resize, format-convert, optimize, preserve animation) via a per-call `transform` option or the standalone `transformImage()` util
 
 ## Quick Setup
 
@@ -76,11 +77,49 @@ export default defineEventHandler(async (event) => {
 })
 ```
 
+### Upload-time image processing
+
+Pass a `transform` option to `upload()` to process an image **before it is stored** — useful for normalizing user uploads or rehosted remote images to a capped size and compact format. The processed bytes are what gets stored, and the file's `meta.mime` / `meta.width` / `meta.height` are updated to match the result.
+
+```ts
+const id = await storage.upload(groupId, file.data, {
+  meta: { name: file.filename!, mime: file.type!, type: 'image', version: 1 },
+  transform: {
+    width: 128,
+    height: 128,
+    format: 'webp', // convert to webp
+    // fit: 'inside' (default), withoutEnlargement: true (default),
+    // quality, background, animated (default true)
+  },
+})
+```
+
+You can also call the util directly (e.g. for images fetched server-side):
+
+```ts
+const res = await transformImage(buffer, { width: 64, format: 'webp' })
+// res: { data: Buffer, mime: 'image/webp', format: 'webp', width: 64, height: 64 }
+```
+
+**`transform` / `transformImage()` options**
+
+| Option | Description |
+|---|---|
+| `width`, `height` | Target box in px (combined with `fit`) |
+| `fit` | Resize fit mode (`inside` default, or `cover`/`contain`/`fill`/`outside`) |
+| `withoutEnlargement` | Never scale up beyond the original (default `true`) |
+| `format` | Output format: `webp` / `png` / `jpeg` / `avif` / `gif` (default: keep input) |
+| `quality` | Output quality `1-100` for lossy formats |
+| `animated` | Preserve all frames of animated inputs (default `true`; only retained when `format` is `webp`/`gif`) |
+| `background` | Background used when flattening transparency |
+
+> Image processing requires the optional [`sharp`](https://sharp.pixelplumbing.com/) peer dependency. Install it (`npm i sharp`) only if you use `transform` / `transformImage()` — calling them without `sharp` throws a clear error. Without a `transform`, `upload()` stores the raw bytes unchanged and needs no extra dependency.
+
 ### `useFileStorage()` API
 
 | Method | Description |
 |---|---|
-| `upload(groupId, data, options?)` | Store a file, returns its ID |
+| `upload(groupId, data, options?)` | Store a file, returns its ID. `options.transform` runs the bytes through Sharp first (see above) |
 | `list(groupId)` | List all files in a group |
 | `get(groupId, id)` | Get a file with data and metadata |
 | `getData(groupId, id)` | Get raw binary data only |

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-filer",
   "configKey": "filer",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -18,6 +18,10 @@ const module = defineNuxtModule({
       {
         name: "useFileStorage",
         from: resolver.resolve("./runtime/server/utils/storage")
+      },
+      {
+        name: "transformImage",
+        from: resolver.resolve("./runtime/server/utils/image")
       }
     ]);
     const providerSpecifier = resolver.resolve("./runtime/server/provider");
@@ -41,7 +45,10 @@ const module = defineNuxtModule({
         name: "FileStorageExternalProvider",
         from: typesSpecifier,
         type: true
-      }
+      },
+      { name: "ImageFormat", from: typesSpecifier, type: true },
+      { name: "ImageTransformOptions", from: typesSpecifier, type: true },
+      { name: "ImageTransformResult", from: typesSpecifier, type: true }
     ]);
     const imageOpt = typeof options.image === "object" && options.image !== null ? options.image : {};
     const imageEnabled = options.image !== false && (imageOpt.enabled ?? true) !== false;

package/dist/runtime/server/handlers/ipx.d.ts

@@ -1,6 +1,3 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<string | void | Buffer<ArrayBufferLike> | {
-    error: {
-        message: string;
-    };
-}>>;
+import { type EventHandler } from 'h3';
+declare const _default: EventHandler<import("h3").EventHandlerRequest, any>;
 export default _default;

package/dist/runtime/server/handlers/ipx.js

@@ -1,4 +1,4 @@
-import { defineEventHandler } from "h3";
+import { defineEventHandler, useBase } from "h3";
 import { createIPX, createIPXH3Handler } from "ipx";
 import { ipxRoute } from "#nuxt-filer-image";
 import { useFileStorageProvider } from "../provider.js";
@@ -36,14 +36,8 @@ let _ipx = null;
 function getHandler() {
   if (!_handler) {
     _ipx = createIPX({ storage: filerStorage });
-    _handler = createIPXH3Handler(_ipx);
+    _handler = useBase(ipxRoute, createIPXH3Handler(_ipx));
   }
   return _handler;
 }
-export default defineEventHandler((event) => {
-  const original = event.path;
-  let sub = original.startsWith(ipxRoute) ? original.slice(ipxRoute.length) : original;
-  if (!sub.startsWith("/")) sub = `/${sub}`;
-  event.path = sub;
-  return getHandler()(event);
-});
+export default defineEventHandler((event) => getHandler()(event));

package/dist/runtime/server/utils/image.d.ts

@@ -0,0 +1,11 @@
+import type { ImageFormat, ImageTransformOptions, ImageTransformResult } from '../../../runtime/types.js';
+export type { ImageFormat, ImageTransformOptions, ImageTransformResult };
+/**
+ * Process an image buffer with sharp: resize within a box, convert format,
+ * optimize, and (by default) preserve animation for multi-frame inputs. Used
+ * for upload-time normalization — see `useFileStorage().upload({ transform })`.
+ *
+ * Requires the optional `sharp` peer dependency; throws a clear error if it is
+ * not installed.
+ */
+export declare function transformImage(data: Buffer | Uint8Array, options?: ImageTransformOptions): Promise<ImageTransformResult>;

package/dist/runtime/server/utils/image.js

@@ -0,0 +1,50 @@
+const MIME_BY_FORMAT = {
+  webp: "image/webp",
+  png: "image/png",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  avif: "image/avif",
+  gif: "image/gif"
+};
+let sharpModule;
+async function loadSharp() {
+  if (sharpModule) return sharpModule;
+  try {
+    sharpModule = (await import("sharp")).default;
+  } catch {
+    throw new Error(
+      "[nuxt-filer] Image transforms require the optional peer dependency `sharp`. Install it with `npm i sharp`."
+    );
+  }
+  return sharpModule;
+}
+export async function transformImage(data, options = {}) {
+  const sharp = await loadSharp();
+  const animated = options.animated ?? true;
+  let pipeline = sharp(data, { animated });
+  if (options.width != null || options.height != null) {
+    pipeline = pipeline.resize({
+      width: options.width,
+      height: options.height,
+      fit: options.fit ?? "inside",
+      withoutEnlargement: options.withoutEnlargement ?? true,
+      background: options.background
+    });
+  }
+  if (options.format) {
+    const formatOptions = options.quality != null ? { quality: options.quality } : {};
+    pipeline = pipeline.toFormat(
+      options.format,
+      formatOptions
+    );
+  }
+  const out = await pipeline.toBuffer({ resolveWithObject: true });
+  const format = out.info.format;
+  return {
+    data: out.data,
+    format,
+    mime: MIME_BY_FORMAT[format] ?? `image/${format}`,
+    width: out.info.width,
+    height: out.info.height
+  };
+}

package/dist/runtime/server/utils/storage.d.ts

@@ -1,8 +1,9 @@
-import type { FileMeta, StoredFile, ExternalRef, FileStorageProvider } from '../../../runtime/types.js';
-export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider };
+import type { FileMeta, StoredFile, ExternalRef, FileStorageProvider, ImageTransformOptions, ImageTransformResult } from '../../../runtime/types.js';
+export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider, ImageTransformOptions, ImageTransformResult, };
 export declare const useFileStorage: () => {
     upload: (groupId: string, data: Buffer | Uint8Array, options?: {
         meta?: FileMeta;
+        transform?: ImageTransformOptions;
     }) => Promise<string>;
     list: (groupId: string) => Promise<StoredFile[]>;
     get: (groupId: string, id: string) => Promise<StoredFile | null>;

package/dist/runtime/server/utils/storage.js

@@ -1,9 +1,20 @@
 import { defu } from "defu";
 import { useFileStorageProvider } from "../provider.js";
+import { transformImage } from "./image.js";
 export const useFileStorage = () => {
   const provider = useFileStorageProvider();
   async function upload(groupId, data, options = {}) {
-    const { id } = await provider.create(groupId, data, options.meta);
+    let payload = data;
+    if (options.transform) {
+      const result = await transformImage(data, options.transform);
+      payload = result.data;
+      if (options.meta) {
+        options.meta.mime = result.mime;
+        options.meta.width = result.width;
+        options.meta.height = result.height;
+      }
+    }
+    const { id } = await provider.create(groupId, payload, options.meta);
     return id;
   }
   async function list(groupId) {

package/dist/runtime/types.d.ts

@@ -7,6 +7,51 @@ export interface FileMeta {
     comment?: string;
     [key: string]: unknown;
 }
+/** Output image format for {@link transformImage}. */
+export type ImageFormat = 'webp' | 'png' | 'jpeg' | 'avif' | 'gif';
+/**
+ * Options for upload-time image processing, backed by the optional `sharp`
+ * peer dependency. Passed via `useFileStorage().upload(.., { transform })` or
+ * to the standalone `transformImage()` util.
+ */
+export interface ImageTransformOptions {
+    /** Target width in px. Combined with `fit` to bound the image. */
+    width?: number;
+    /** Target height in px. Combined with `fit` to bound the image. */
+    height?: number;
+    /**
+     * How the image is resized to fit `width`/`height`. Mirrors sharp's `fit`.
+     * Default: `'inside'` (preserve aspect ratio, fit within the box).
+     */
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    /** Never scale the image up beyond its original size. Default: `true`. */
+    withoutEnlargement?: boolean;
+    /** Output format. Default: keep the input's format. */
+    format?: ImageFormat;
+    /** Output quality (1-100) for lossy formats (webp/jpeg/avif). */
+    quality?: number;
+    /**
+     * Preserve every frame of multi-frame inputs (animated webp/gif). Default:
+     * `true`; harmless for static images. Animation is only retained when the
+     * output `format` is animation-capable (`webp`/`gif`).
+     */
+    animated?: boolean;
+    /** Background used when flattening transparency (e.g. for `contain`/jpeg). */
+    background?: string;
+}
+/** Result of {@link transformImage}: the processed bytes plus resolved metadata. */
+export interface ImageTransformResult {
+    /** The processed image bytes. */
+    data: Buffer;
+    /** MIME type of the processed image, e.g. `image/webp`. */
+    mime: string;
+    /** Resolved output format, e.g. `webp`. */
+    format: string;
+    /** Width of the processed image in px, if sharp could determine it. */
+    width?: number;
+    /** Height of the processed image in px, if sharp could determine it. */
+    height?: number;
+}
 export interface ExternalRef {
     /** External system identifier, e.g. 'jira', 'sharepoint' */
     source: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
@@ -64,13 +64,15 @@
     "eslint": "^10.1.0",
     "ipx": "^3.1.1",
     "nuxt": "^4.4.2",
+    "sharp": "^0.34.5",
     "typescript": "~6.0.2",
     "vitest": "^4.1.2",
     "vue-tsc": "^3.2.6"
   },
   "peerDependencies": {
     "@nuxt/image": "^2.0.0",
-    "ipx": "^3.0.0"
+    "ipx": "^3.0.0",
+    "sharp": "^0.33.0 || ^0.34.0"
   },
   "peerDependenciesMeta": {
     "@nuxt/image": {
@@ -78,12 +80,16 @@
     },
     "ipx": {
       "optional": true
+    },
+    "sharp": {
+      "optional": true
     }
   },
   "packageManager": "pnpm@10.33.0",
   "pnpm": {
     "onlyBuiltDependencies": [
-      "esbuild"
+      "esbuild",
+      "sharp"
     ]
   }
 }

package/src/runtime/server/handlers/ipx.ts

@@ -1,4 +1,4 @@
-import { defineEventHandler } from 'h3';
+import { defineEventHandler, useBase, type EventHandler } from 'h3';
 import { createIPX, createIPXH3Handler, type IPX, type IPXStorage } from 'ipx';
 // @ts-expect-error virtual module injected by the module
 import { ipxRoute } from '#nuxt-filer-image';
@@ -41,24 +41,20 @@ const filerStorage: IPXStorage = {
   },
 };
 
-let _handler: ReturnType<typeof createIPXH3Handler> | null = null;
+let _handler: EventHandler | null = null;
 let _ipx: IPX | null = null;
-function getHandler() {
+function getHandler(): EventHandler {
   if (!_handler) {
     _ipx = createIPX({ storage: filerStorage });
-    _handler = createIPXH3Handler(_ipx);
+    // IPX expects to see `/<modifiers>/<groupId>/<fileId>`, so strip the
+    // configured base prefix first. We delegate to h3's `useBase` rather than
+    // assigning `event.path` — `event.path` is a getter-only accessor (it
+    // reads back `event._path || req.url`), so writing to it throws
+    // "Cannot set property path ... which has only a getter". `useBase`
+    // rewrites `_path`/`req.url` for the inner handler and restores them after.
+    _handler = useBase(ipxRoute, createIPXH3Handler(_ipx));
   }
   return _handler;
 }
 
-export default defineEventHandler((event) => {
-  // Strip the configured base prefix so IPX sees the URL it expects:
-  // `/<modifiers>/<groupId>/<fileId>`.
-  const original = event.path;
-  let sub = original.startsWith(ipxRoute)
-    ? original.slice((ipxRoute as string).length)
-    : original;
-  if (!sub.startsWith('/')) sub = `/${sub}`;
-  event.path = sub;
-  return getHandler()(event);
-});
+export default defineEventHandler((event) => getHandler()(event));

package/src/runtime/server/utils/image.ts

@@ -0,0 +1,82 @@
+import type {
+  ImageFormat,
+  ImageTransformOptions,
+  ImageTransformResult,
+} from '../../../runtime/types';
+
+export type { ImageFormat, ImageTransformOptions, ImageTransformResult };
+
+const MIME_BY_FORMAT: Record<string, string> = {
+  webp: 'image/webp',
+  png: 'image/png',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  avif: 'image/avif',
+  gif: 'image/gif',
+};
+
+// `sharp` is an optional peer dependency — resolve it lazily and cache the
+// module so unrelated installs never pay for the native binary.
+type SharpModule = typeof import('sharp');
+let sharpModule: SharpModule | undefined;
+
+async function loadSharp(): Promise<SharpModule> {
+  if (sharpModule) return sharpModule;
+  try {
+    sharpModule = (await import('sharp')).default as unknown as SharpModule;
+  }
+  catch {
+    throw new Error(
+      '[nuxt-filer] Image transforms require the optional peer dependency `sharp`. Install it with `npm i sharp`.'
+    );
+  }
+  return sharpModule;
+}
+
+/**
+ * Process an image buffer with sharp: resize within a box, convert format,
+ * optimize, and (by default) preserve animation for multi-frame inputs. Used
+ * for upload-time normalization — see `useFileStorage().upload({ transform })`.
+ *
+ * Requires the optional `sharp` peer dependency; throws a clear error if it is
+ * not installed.
+ */
+export async function transformImage(
+  data: Buffer | Uint8Array,
+  options: ImageTransformOptions = {}
+): Promise<ImageTransformResult> {
+  const sharp = await loadSharp();
+
+  const animated = options.animated ?? true;
+  let pipeline = sharp(data, { animated });
+
+  if (options.width != null || options.height != null) {
+    pipeline = pipeline.resize({
+      width: options.width,
+      height: options.height,
+      fit: options.fit ?? 'inside',
+      withoutEnlargement: options.withoutEnlargement ?? true,
+      background: options.background,
+    });
+  }
+
+  if (options.format) {
+    const formatOptions
+      = options.quality != null ? { quality: options.quality } : {};
+    pipeline = pipeline.toFormat(
+      options.format as keyof import('sharp').FormatEnum,
+      formatOptions
+    );
+  }
+
+  const out = await pipeline.toBuffer({ resolveWithObject: true });
+  const format = out.info.format;
+
+  return {
+    data: out.data,
+    format,
+    mime: MIME_BY_FORMAT[format] ?? `image/${format}`,
+    width: out.info.width,
+    height: out.info.height,
+  };
+}

package/src/runtime/server/utils/storage.ts

@@ -4,10 +4,20 @@ import type {
   StoredFile,
   ExternalRef,
   FileStorageProvider,
+  ImageTransformOptions,
+  ImageTransformResult,
 } from '../../../runtime/types';
 import { useFileStorageProvider } from '../provider';
+import { transformImage } from './image';
 
-export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider };
+export type {
+  FileMeta,
+  StoredFile,
+  ExternalRef,
+  FileStorageProvider,
+  ImageTransformOptions,
+  ImageTransformResult,
+};
 
 export const useFileStorage = () => {
   const provider = useFileStorageProvider();
@@ -15,9 +25,23 @@ export const useFileStorage = () => {
   async function upload(
     groupId: string,
     data: Buffer | Uint8Array,
-    options: { meta?: FileMeta } = {}
+    options: { meta?: FileMeta; transform?: ImageTransformOptions } = {}
   ): Promise<string> {
-    const { id } = await provider.create(groupId, data, options.meta);
+    let payload = data;
+
+    // Optional upload-time image processing (requires the `sharp` peer dep).
+    // The stored bytes and the metadata's mime/dimensions reflect the result.
+    if (options.transform) {
+      const result = await transformImage(data, options.transform);
+      payload = result.data;
+      if (options.meta) {
+        options.meta.mime = result.mime;
+        options.meta.width = result.width;
+        options.meta.height = result.height;
+      }
+    }
+
+    const { id } = await provider.create(groupId, payload, options.meta);
     return id;
   }
 

package/src/runtime/types.ts

@@ -8,6 +8,54 @@ export interface FileMeta {
   [key: string]: unknown;
 }
 
+/** Output image format for {@link transformImage}. */
+export type ImageFormat = 'webp' | 'png' | 'jpeg' | 'avif' | 'gif';
+
+/**
+ * Options for upload-time image processing, backed by the optional `sharp`
+ * peer dependency. Passed via `useFileStorage().upload(.., { transform })` or
+ * to the standalone `transformImage()` util.
+ */
+export interface ImageTransformOptions {
+  /** Target width in px. Combined with `fit` to bound the image. */
+  width?: number;
+  /** Target height in px. Combined with `fit` to bound the image. */
+  height?: number;
+  /**
+   * How the image is resized to fit `width`/`height`. Mirrors sharp's `fit`.
+   * Default: `'inside'` (preserve aspect ratio, fit within the box).
+   */
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+  /** Never scale the image up beyond its original size. Default: `true`. */
+  withoutEnlargement?: boolean;
+  /** Output format. Default: keep the input's format. */
+  format?: ImageFormat;
+  /** Output quality (1-100) for lossy formats (webp/jpeg/avif). */
+  quality?: number;
+  /**
+   * Preserve every frame of multi-frame inputs (animated webp/gif). Default:
+   * `true`; harmless for static images. Animation is only retained when the
+   * output `format` is animation-capable (`webp`/`gif`).
+   */
+  animated?: boolean;
+  /** Background used when flattening transparency (e.g. for `contain`/jpeg). */
+  background?: string;
+}
+
+/** Result of {@link transformImage}: the processed bytes plus resolved metadata. */
+export interface ImageTransformResult {
+  /** The processed image bytes. */
+  data: Buffer;
+  /** MIME type of the processed image, e.g. `image/webp`. */
+  mime: string;
+  /** Resolved output format, e.g. `webp`. */
+  format: string;
+  /** Width of the processed image in px, if sharp could determine it. */
+  width?: number;
+  /** Height of the processed image in px, if sharp could determine it. */
+  height?: number;
+}
+
 export interface ExternalRef {
   /** External system identifier, e.g. 'jira', 'sharepoint' */
   source: string;