nuxt-filer 0.0.17 → 0.0.19

package/README.md

@@ -117,6 +117,34 @@ const res = await transformImage(buffer, { width: 64, format: 'webp' })
 
 > 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.
 
+### Thumbnails and PDF previews with `generateThumbnail()`
+
+Builds a preview image from a stored file: images are resized with Sharp, PDFs
+get a page (the first by default) rendered and then resized. It returns
+`null` instead of throwing for unsupported types, unreadable input, or missing
+optional dependencies, so it can run on every upload:
+
+```ts
+const file = await readUploadedFile(event)
+const id = await storage.upload('docs', file.data, { meta: { name: file.name, mime: file.type, type: 'document', version: 1 } })
+
+const thumb = await generateThumbnail(file.data, file.type, { width: 300, height: 200 })
+if (thumb) {
+  await storage.upload('docs', thumb.data, {
+    meta: { name: `thumb_${file.name}`, mime: thumb.mime, type: 'thumbnail', version: 1 },
+  })
+}
+```
+
+- Options are those of `transformImage()` plus `page` (PDF page, default `1`).
+  Defaults: a 300×300 `inside` box, `webp`, and the first frame only for
+  animated images (`animated: true` keeps animation).
+- Requires `sharp`; PDFs additionally need [`unpdf`](https://github.com/unjs/unpdf)
+  and `@napi-rs/canvas` (`npm i unpdf @napi-rs/canvas`). All are optional peer
+  dependencies; when one is missing, a warning is logged once and `null` returned.
+- On-request transforms (the IPX route, or imgproxy) can't render PDFs, so a
+  stored preview like this is the way to show one.
+
 ### `useFileStorage()` API
 
 | Method | Description |
@@ -124,8 +152,9 @@ const res = await transformImage(buffer, { width: 64, format: 'webp' })
 | `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 |
+| `head(groupId, id)` | Get a file's metadata and timestamps without reading its bytes |
 | `getData(groupId, id)` | Get raw binary data only |
-| `getMeta(id)` | Get metadata only |
+| `getMeta(id)` | Get metadata only. Searches all groups, which is slow on large stores — prefer `head(groupId, id)` |
 | `updateMeta(id, meta)` | Deep-merge metadata update |
 | `remove(groupId, id)` | Delete a file |
 | `clear(groupId)` | Delete all files in a group |
@@ -138,6 +167,35 @@ const res = await transformImage(buffer, { width: 64, format: 'webp' })
 | `external?.push(groupId, id, data, meta)` | Push to external system |
 | `external?.pull(groupId, ref)` | Pull from external system |
 
+### Validating uploads with `readUploadedFile()`
+
+Reads a file from a `multipart/form-data` request and validates it, throwing a
+400 (no file), 413 (too large) or 415 (type not allowed) with a message naming
+the file and the limit:
+
+```ts
+// server/api/models.post.ts
+export default defineEventHandler(async (event) => {
+  const file = await readUploadedFile(event, {
+    types: ['image', '.stl', '.3mf', 'application/pdf'],
+    maxSize: '50MB',
+  })
+  const id = await useFileStorage().upload(file.fields.group ?? 'uploads', file.data, {
+    meta: { name: file.name, mime: file.type, type: 'model', version: 1 },
+  })
+  return { id }
+})
+```
+
+- `types` uses the syntax of the HTML `accept` attribute: exact MIME types
+  (`'image/png'`), families (`'image'` or `'image/*'`) and extensions
+  (`'.stl'`). Extensions help for formats browsers send without a MIME type.
+- `maxSize` takes bytes or a string like `'500KB'`, `'2MB'` (1024-based). An
+  oversized request is rejected from its `Content-Length` before the body is read.
+- `field` picks the form field (default `'file'`); the result's `fields` holds
+  the other, non-file form fields.
+- `readUploadedFiles(event, { ..., max })` reads several files from the same field.
+
 ### Serving raw files with `sendStoredFile()`
 
 The IPX route serves **images** with full HTTP caching. For everything else — original PDFs, non-image downloads, the unprocessed bytes of any file — `sendStoredFile()` streams a stored file back through an H3 event with the same revalidation story.
@@ -480,6 +538,9 @@ export default defineNitroPlugin(() => {
 interface FileStorageProvider {
   create(groupId: string, data: Buffer | Uint8Array, meta?: FileMeta): Promise<{ id: string }>
   get(groupId: string, id: string): Promise<StoredFile | null>
+  // Optional: metadata without the bytes. Used by sendStoredFile and the IPX
+  // route to answer 304s without reading the file; falls back to get().
+  head?(groupId: string, id: string): Promise<StoredFile | null>
   getData(groupId: string, id: string): Promise<Buffer | null>
   getMeta(id: string): Promise<FileMeta | null>
   list(groupId: string): Promise<StoredFile[]>

package/dist/module.json

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

package/dist/module.mjs

@@ -21,6 +21,18 @@ const module = defineNuxtModule({
         name: "useFileStorage",
         from: resolver.resolve("./runtime/server/utils/storage")
       },
+      {
+        name: "readUploadedFile",
+        from: resolver.resolve("./runtime/server/utils/upload")
+      },
+      {
+        name: "readUploadedFiles",
+        from: resolver.resolve("./runtime/server/utils/upload")
+      },
+      {
+        name: "generateThumbnail",
+        from: resolver.resolve("./runtime/server/utils/thumbnail")
+      },
       {
         name: "transformImage",
         from: resolver.resolve("./runtime/server/utils/image")

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

@@ -6,7 +6,7 @@ import {
 } from "h3";
 import * as ipxModule from "ipx";
 import { ipxRoute } from "#nuxt-filer-image";
-import { useFileStorageProvider } from "../provider.js";
+import { headStoredFile, useFileStorageProvider } from "../provider.js";
 function parseId(id) {
   const trimmed = id.replace(/^\/+/, "");
   const lastSlash = trimmed.lastIndexOf("/");
@@ -19,8 +19,7 @@ const filerStorage = {
     const parsed = parseId(id);
     if (!parsed) return void 0;
     const [groupId, fileId] = parsed;
-    const provider = useFileStorageProvider();
-    const file = await provider.get(groupId, fileId);
+    const file = await headStoredFile(useFileStorageProvider(), groupId, fileId);
     if (!file) return void 0;
     const mtime = file.updatedAt ?? file.createdAt ?? /* @__PURE__ */ new Date();
     return {

package/dist/runtime/server/provider.d.ts

@@ -1,3 +1,8 @@
-import type { FileStorageProvider } from '../../runtime/types.js';
+import type { FileStorageProvider, StoredFile } from '../../runtime/types.js';
 export declare function setFileStorageProvider(provider: FileStorageProvider): void;
 export declare function useFileStorageProvider(): FileStorageProvider;
+/**
+ * A file's metadata without its bytes when the provider supports `head()`;
+ * otherwise `get()`, whose `data` callers can reuse instead of reading again.
+ */
+export declare function headStoredFile(provider: FileStorageProvider, groupId: string, id: string): Promise<StoredFile | null>;

package/dist/runtime/server/provider.js

@@ -10,3 +10,6 @@ export function useFileStorageProvider() {
   }
   return _provider;
 }
+export async function headStoredFile(provider, groupId, id) {
+  return provider.head ? provider.head(groupId, id) : provider.get(groupId, id);
+}

package/dist/runtime/server/providers/drizzle.js

@@ -130,6 +130,12 @@ export function createDrizzleProvider(options) {
       if (!data) return null;
       return { id, groupId, data, meta: { ...EMPTY_META } };
     },
+    async head(groupId, id) {
+      const c = await ready();
+      const row = await findRow(id, groupId);
+      if (row) return toStoredFile(c, row);
+      return await blobs.get(blobKey(groupId, id)) ? { id, groupId, meta: { ...EMPTY_META } } : null;
+    },
     async getData(groupId, id) {
       return blobs.get(blobKey(groupId, id));
     },

package/dist/runtime/server/providers/s3.js

@@ -65,6 +65,12 @@ export function createS3Provider(options) {
       if (!data && !meta) return null;
       return toStoredFile(id, groupId, meta, data ?? void 0);
     },
+    async head(groupId, id) {
+      const client = await getClient();
+      const meta = await readMeta(client, metaKey(groupId, id));
+      if (!meta && !await client.head(dataKey(groupId, id))) return null;
+      return toStoredFile(id, groupId, meta);
+    },
     async getData(groupId, id) {
       return (await getClient()).get(dataKey(groupId, id));
     },

package/dist/runtime/server/providers/unstorage.js

@@ -38,6 +38,18 @@ export function createUnstorageProvider(storageName) {
         updatedAt: metaData?._updatedAt ? new Date(metaData._updatedAt) : void 0
       };
     },
+    async head(groupId, id) {
+      const storage = getStorage();
+      const metaData = await storage.getItem(metaKey(groupId, id));
+      if (!metaData && !await storage.hasItem(dataKey(groupId, id))) return null;
+      return {
+        id,
+        groupId,
+        meta: stripInternal(metaData),
+        createdAt: metaData?._createdAt ? new Date(metaData._createdAt) : void 0,
+        updatedAt: metaData?._updatedAt ? new Date(metaData._updatedAt) : void 0
+      };
+    },
     async getData(groupId, id) {
       return await getStorage().getItemRaw(dataKey(groupId, id));
     },

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

@@ -4,10 +4,11 @@ import {
   setResponseStatus,
   createError
 } from "h3";
-import { useFileStorageProvider } from "../provider.js";
+import { headStoredFile, useFileStorageProvider } from "../provider.js";
 const DEFAULT_MAX_AGE = 60 * 60 * 24 * 365;
 function fileMtime(file) {
-  return file.updatedAt ?? file.createdAt ?? void 0;
+  const mtime = file.updatedAt ?? file.createdAt;
+  return mtime ? new Date(Math.floor(mtime.getTime() / 1e3) * 1e3) : void 0;
 }
 function cacheValidators(file) {
   const mtime = fileMtime(file);
@@ -20,7 +21,7 @@ function contentDisposition(type, name) {
 }
 export async function sendStoredFile(event, groupId, id, options = {}) {
   const provider = useFileStorageProvider();
-  const file = await provider.get(groupId, id);
+  const file = await headStoredFile(provider, groupId, id);
   if (!file) {
     throw createError({ statusCode: 404, statusMessage: "File not found" });
   }
@@ -36,7 +37,7 @@ export async function sendStoredFile(event, groupId, id, options = {}) {
     setResponseHeader(event, "last-modified", lastModified.toUTCString());
   const ifNoneMatch = getRequestHeader(event, "if-none-match");
   const ifModifiedSince = getRequestHeader(event, "if-modified-since");
-  const notModified = etag ? ifNoneMatch === etag : !!lastModified && !!ifModifiedSince && lastModified.getTime() <= Date.parse(ifModifiedSince);
+  const notModified = ifNoneMatch ? !!etag && ifNoneMatch === etag : !!lastModified && !!ifModifiedSince && lastModified.getTime() <= Date.parse(ifModifiedSince);
   if (notModified) {
     setResponseStatus(event, 304);
     return null;
@@ -54,7 +55,7 @@ export async function sendStoredFile(event, groupId, id, options = {}) {
       options.filename ?? file.meta.name
     )
   );
-  const data = await provider.getData(groupId, id);
+  const data = file.data ?? await provider.getData(groupId, id);
   if (!data) {
     throw createError({ statusCode: 404, statusMessage: "File not found" });
   }

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

@@ -7,6 +7,7 @@ export declare const useFileStorage: () => {
     }) => Promise<string>;
     list: (groupId: string) => Promise<StoredFile[]>;
     get: (groupId: string, id: string) => Promise<StoredFile | null>;
+    head: (groupId: string, id: string) => Promise<StoredFile | null>;
     getData: (groupId: string, id: string) => Promise<Buffer | null>;
     getMeta: (id: string) => Promise<FileMeta | null>;
     updateMeta: (id: string, meta: Partial<FileMeta>) => Promise<void>;

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

@@ -1,5 +1,5 @@
 import { defu } from "defu";
-import { useFileStorageProvider } from "../provider.js";
+import { headStoredFile, useFileStorageProvider } from "../provider.js";
 import { transformImage } from "./image.js";
 import { transformWithService, useImageService } from "./image-service-runtime.js";
 export const useFileStorage = () => {
@@ -25,6 +25,10 @@ export const useFileStorage = () => {
   async function get(groupId, id) {
     return await provider.get(groupId, id);
   }
+  async function head(groupId, id) {
+    const file = await headStoredFile(provider, groupId, id);
+    return file && { ...file, data: void 0 };
+  }
   async function getData(groupId, id) {
     return await provider.getData(groupId, id);
   }
@@ -80,6 +84,7 @@ export const useFileStorage = () => {
     upload,
     list,
     get,
+    head,
     getData,
     getMeta,
     updateMeta,

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

@@ -0,0 +1,19 @@
+import type { ImageTransformOptions, ImageTransformResult } from '../../../runtime/types.js';
+export interface ThumbnailOptions extends ImageTransformOptions {
+    /** PDF page to render. Default: `1`. */
+    page?: number;
+}
+/**
+ * Generate a preview image for a stored file: images are resized with sharp,
+ * PDFs have a page (default: the first) rendered with `unpdf` and then resized.
+ *
+ * Returns `null` — never throws — when the type isn't supported, the input
+ * can't be decoded, or the optional dependencies aren't installed (`sharp`,
+ * plus `unpdf` and `@napi-rs/canvas` for PDFs; a warning is logged once).
+ *
+ * ```ts
+ * const thumb = await generateThumbnail(file.data, file.type, { width: 300, height: 200 })
+ * if (thumb) await storage.upload(group, thumb.data, { meta: { ...meta, mime: thumb.mime } })
+ * ```
+ */
+export declare function generateThumbnail(data: Buffer | Uint8Array, mime: string, options?: ThumbnailOptions): Promise<ImageTransformResult | null>;

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

@@ -0,0 +1,54 @@
+import { consola } from "consola";
+import { transformImage } from "./image.js";
+const DEFAULTS = {
+  width: 300,
+  height: 300,
+  fit: "inside",
+  format: "webp",
+  // A thumbnail shows the first frame; pass `animated: true` to keep animation.
+  animated: false
+};
+const warned = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  consola.warn(message);
+}
+function isMissingModule(error) {
+  for (let e = error; e; e = e.cause) {
+    if (e.code === "ERR_MODULE_NOT_FOUND" || e.code === "MODULE_NOT_FOUND") return true;
+    if (/Cannot find (?:module|package)|Failed to load url/i.test(String(e.message))) return true;
+  }
+  return false;
+}
+async function renderPdfPage(data, page, width) {
+  const { renderPageAsImage } = await import("unpdf");
+  const png = await renderPageAsImage(new Uint8Array(data), page, {
+    canvasImport: () => import("@napi-rs/canvas"),
+    width
+  });
+  return Buffer.from(png);
+}
+export async function generateThumbnail(data, mime, options = {}) {
+  const { page = 1, ...transform } = { ...DEFAULTS, ...options };
+  const type = mime.toLowerCase().split(";")[0].trim();
+  try {
+    if (type === "application/pdf") {
+      const width = Math.min(2 * Math.max(transform.width ?? 0, transform.height ?? 0, 300), 4096);
+      const png = await renderPdfPage(data, page, width);
+      return await transformImage(png, transform);
+    }
+    if (type.startsWith("image/")) {
+      return await transformImage(data, transform);
+    }
+    return null;
+  } catch (error) {
+    if (isMissingModule(error) || /optional peer dependency `sharp`/.test(String(error?.message))) {
+      warnOnce(
+        type,
+        type === "application/pdf" ? "[nuxt-filer] generateThumbnail: PDF previews need the optional dependencies `unpdf`, `@napi-rs/canvas` and `sharp`." : "[nuxt-filer] generateThumbnail: image previews need the optional dependency `sharp`."
+      );
+    }
+    return null;
+  }
+}

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

@@ -0,0 +1,57 @@
+import { type H3Event } from 'h3';
+/** A file read from a `multipart/form-data` request. */
+export interface UploadedFile {
+    /** The file's bytes. */
+    data: Buffer;
+    /** The client-supplied filename. */
+    name: string;
+    /** MIME type as sent by the client, `application/octet-stream` when missing. */
+    type: string;
+    /** Size in bytes. */
+    size: number;
+    /** The request's non-file form fields, e.g. `{ group: 'models' }`. */
+    fields: Record<string, string>;
+}
+export interface ReadUploadedFileOptions {
+    /**
+     * Accepted types, using the syntax of the HTML `accept` attribute plus a
+     * shorthand for families: an exact MIME type (`'image/png'`), a family
+     * (`'image'` or `'image/*'`), or an extension (`'.stl'`). Any match is
+     * enough. Default: anything.
+     */
+    types?: string[];
+    /** Max size per file: bytes, or a string like `'500KB'` / `'2MB'` / `'1GB'` (1024-based). */
+    maxSize?: number | string;
+    /** Form field holding the file(s). Default: `'file'`. */
+    field?: string;
+}
+export interface ReadUploadedFilesOptions extends ReadUploadedFileOptions {
+    /** Max number of files. Default: unlimited. */
+    max?: number;
+}
+/** Parse `'2MB'`-style sizes (1024-based); numbers are bytes. */
+export declare function parseSize(size: number | string): number;
+/** Whether a file matches one of the accepted `types` (see {@link ReadUploadedFileOptions.types}). */
+export declare function matchesType(file: {
+    name: string;
+    type: string;
+}, types: string[]): boolean;
+/**
+ * Read and validate a single uploaded file from a `multipart/form-data`
+ * request. Throws an H3 error — 400 when no file is present, 413 when it
+ * exceeds `maxSize`, 415 when its type isn't accepted — with a short
+ * `statusMessage` and a `message` naming the file and the limit.
+ *
+ * ```ts
+ * export default defineEventHandler(async (event) => {
+ *   const file = await readUploadedFile(event, { types: ['image'], maxSize: '5MB' })
+ *   const id = await useFileStorage().upload('avatars', file.data, {
+ *     meta: { name: file.name, mime: file.type, type: 'image', version: 1 },
+ *   })
+ *   return { id }
+ * })
+ * ```
+ */
+export declare function readUploadedFile(event: H3Event, options?: ReadUploadedFileOptions): Promise<UploadedFile>;
+/** Like {@link readUploadedFile}, for several files in the same form field. */
+export declare function readUploadedFiles(event: H3Event, options?: ReadUploadedFilesOptions): Promise<UploadedFile[]>;

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

@@ -0,0 +1,81 @@
+import {
+  createError,
+  getRequestHeader,
+  readMultipartFormData
+} from "h3";
+const UNITS = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+export function parseSize(size) {
+  if (typeof size === "number") return size;
+  const match = size.trim().toUpperCase().match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)$/);
+  if (!match) throw new Error(`[nuxt-filer] invalid size "${size}" (use e.g. 500KB, 2MB, 1GB)`);
+  return Math.floor(Number(match[1]) * UNITS[match[2]]);
+}
+function formatSize(bytes) {
+  for (const unit of ["GB", "MB", "KB"]) {
+    if (bytes >= UNITS[unit] && bytes % UNITS[unit] === 0) return `${bytes / UNITS[unit]} ${unit}`;
+  }
+  return bytes >= UNITS.MB ? `${(bytes / UNITS.MB).toFixed(1)} MB` : `${bytes} B`;
+}
+export function matchesType(file, types) {
+  const mime = file.type.toLowerCase();
+  const name = file.name.toLowerCase();
+  return types.some((raw) => {
+    const type = raw.trim().toLowerCase();
+    if (type.startsWith(".")) return name.endsWith(type);
+    if (type.endsWith("/*")) return mime.startsWith(type.slice(0, -1));
+    if (!type.includes("/")) return mime.startsWith(`${type}/`);
+    return mime === type;
+  });
+}
+const MULTIPART_OVERHEAD = 64 * 1024;
+async function readFiles(event, options) {
+  const field = options.field ?? "file";
+  const maxSize = options.maxSize === void 0 ? void 0 : parseSize(options.maxSize);
+  if (maxSize !== void 0 && options.max !== void 0) {
+    const length = Number(getRequestHeader(event, "content-length"));
+    if (length > (maxSize + MULTIPART_OVERHEAD) * options.max) {
+      throw createError({ statusCode: 413, statusMessage: "File too large", message: `File too large (max ${formatSize(maxSize)})` });
+    }
+  }
+  const parts = await readMultipartFormData(event) ?? [];
+  const fields = {};
+  for (const part of parts) {
+    if (part.name && part.filename === void 0) fields[part.name] = part.data.toString("utf8");
+  }
+  const files = parts.filter((part) => part.name === field && part.filename).map((part) => ({
+    data: part.data,
+    name: part.filename,
+    type: part.type || "application/octet-stream",
+    size: part.data.length,
+    fields
+  }));
+  if (!files.length) {
+    throw createError({ statusCode: 400, statusMessage: "No file provided", message: `No file provided (expected form field "${field}")` });
+  }
+  if (options.max !== void 0 && files.length > options.max) {
+    throw createError({ statusCode: 400, statusMessage: "Too many files", message: `Too many files (max ${options.max})` });
+  }
+  for (const file of files) {
+    if (maxSize !== void 0 && file.size > maxSize) {
+      throw createError({
+        statusCode: 413,
+        statusMessage: "File too large",
+        message: `File "${file.name}" is too large (max ${formatSize(maxSize)})`
+      });
+    }
+    if (options.types && !matchesType(file, options.types)) {
+      throw createError({
+        statusCode: 415,
+        statusMessage: "Unsupported file type",
+        message: `File type of "${file.name}" is not allowed (allowed: ${options.types.join(", ")})`
+      });
+    }
+  }
+  return files;
+}
+export async function readUploadedFile(event, options = {}) {
+  return (await readFiles(event, { ...options, max: 1 }))[0];
+}
+export async function readUploadedFiles(event, options = {}) {
+  return readFiles(event, options);
+}

package/dist/runtime/types.d.ts

@@ -135,6 +135,11 @@ export interface FileStorageProvider {
         id: string;
     }>;
     get(groupId: string, id: string): Promise<StoredFile | null>;
+    /**
+     * Like {@link get} but without reading the bytes (`data` is undefined).
+     * Optional: when a provider doesn't implement it, callers fall back to `get()`.
+     */
+    head?(groupId: string, id: string): Promise<StoredFile | null>;
     getData(groupId: string, id: string): Promise<Buffer | null>;
     getMeta(id: string): Promise<FileMeta | null>;
     list(groupId: string): Promise<StoredFile[]>;

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Niki2k1/nuxt-filer.git"
+    "url": "git+https://github.com/Niki2k1/ablage.git"
   },
-  "homepage": "https://github.com/Niki2k1/nuxt-filer#readme",
+  "homepage": "https://github.com/Niki2k1/ablage#readme",
   "bugs": {
-    "url": "https://github.com/Niki2k1/nuxt-filer/issues"
+    "url": "https://github.com/Niki2k1/ablage/issues"
   },
   "license": "MIT",
   "author": "Niki2k1",
@@ -47,6 +47,7 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
+    "@napi-rs/canvas": "^1.0.10",
     "@nuxt/devtools": "^3.2.4",
     "@nuxt/eslint-config": "^1.15.2",
     "@nuxt/image": "^2.1.0",
@@ -63,17 +64,23 @@
     "nuxt": "^4.4.2",
     "sharp": "^0.35.5",
     "typescript": "~6.0.2",
+    "unpdf": "^1.8.1",
     "vitest": "^4.1.2",
     "vue-tsc": "^3.2.6"
   },
   "peerDependencies": {
+    "@napi-rs/canvas": "^0.1.69 || ^1.0.0",
     "@nuxt/image": "^2.0.0",
     "aws4fetch": "^1.0.20",
     "drizzle-orm": ">=0.36.0 <1.0.0 || >=1.0.0-0 <2.0.0",
     "ipx": "^3.0.0 || ^4.0.0-0",
-    "sharp": "^0.33.0 || ^0.34.0 || ^0.35.0"
+    "sharp": "^0.33.0 || ^0.34.0 || ^0.35.0",
+    "unpdf": "^1.8.0"
   },
   "peerDependenciesMeta": {
+    "@napi-rs/canvas": {
+      "optional": true
+    },
     "@nuxt/image": {
       "optional": true
     },
@@ -88,6 +95,9 @@
     },
     "sharp": {
       "optional": true
+    },
+    "unpdf": {
+      "optional": true
     }
   },
   "scripts": {

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

@@ -12,7 +12,7 @@ import * as ipxModule from 'ipx';
 import type { IPXStorage } from 'ipx';
 // @ts-expect-error virtual module injected by the module
 import { ipxRoute } from '#nuxt-filer-image';
-import { useFileStorageProvider } from '../provider';
+import { headStoredFile, useFileStorageProvider } from '../provider';
 
 /**
  * Maps an IPX `id` (the path after the modifiers segment) to a `(groupId, fileId)`
@@ -32,8 +32,8 @@ const filerStorage: IPXStorage = {
     const parsed = parseId(id);
     if (!parsed) return undefined;
     const [groupId, fileId] = parsed;
-    const provider = useFileStorageProvider();
-    const file = await provider.get(groupId, fileId);
+    // Metadata only; IPX reads the bytes through getData() when it renders.
+    const file = await headStoredFile(useFileStorageProvider(), groupId, fileId);
     if (!file) return undefined;
     const mtime = file.updatedAt ?? file.createdAt ?? new Date();
     return {

package/src/runtime/server/provider.ts

@@ -1,4 +1,4 @@
-import type { FileStorageProvider } from '../../runtime/types';
+import type { FileStorageProvider, StoredFile } from '../../runtime/types';
 
 let _provider: FileStorageProvider | null = null;
 
@@ -14,3 +14,15 @@ export function useFileStorageProvider(): FileStorageProvider {
   }
   return _provider;
 }
+
+/**
+ * A file's metadata without its bytes when the provider supports `head()`;
+ * otherwise `get()`, whose `data` callers can reuse instead of reading again.
+ */
+export async function headStoredFile(
+  provider: FileStorageProvider,
+  groupId: string,
+  id: string
+): Promise<StoredFile | null> {
+  return provider.head ? provider.head(groupId, id) : provider.get(groupId, id);
+}

package/src/runtime/server/providers/drizzle.ts

@@ -230,6 +230,15 @@ export function createDrizzleProvider(options: DrizzleProviderOptions): FileStor
       return { id, groupId, data, meta: { ...EMPTY_META } };
     },
 
+    async head(groupId, id) {
+      const c = await ready();
+      const row = await findRow(id, groupId);
+      if (row) return toStoredFile(c, row);
+      // No row: only bytes stored without metadata (e.g. not yet imported).
+      // The blob store has no existence check, so this rare path reads them.
+      return (await blobs.get(blobKey(groupId, id))) ? { id, groupId, meta: { ...EMPTY_META } } : null;
+    },
+
     async getData(groupId, id) {
       return blobs.get(blobKey(groupId, id));
     },

package/src/runtime/server/providers/s3.ts

@@ -148,6 +148,13 @@ export function createS3Provider(options: S3ProviderOptions): FileStorageProvide
       return toStoredFile(id, groupId, meta, data ?? undefined);
     },
 
+    async head(groupId, id) {
+      const client = await getClient();
+      const meta = await readMeta(client, metaKey(groupId, id));
+      if (!meta && !(await client.head(dataKey(groupId, id)))) return null;
+      return toStoredFile(id, groupId, meta);
+    },
+
     async getData(groupId, id) {
       return (await getClient()).get(dataKey(groupId, id));
     },

package/src/runtime/server/providers/unstorage.ts

@@ -67,6 +67,26 @@ export function createUnstorageProvider(
       };
     },
 
+    async head(groupId, id) {
+      const storage = getStorage();
+      const metaData = await storage.getItem<
+        FileMeta & { _createdAt?: string; _updatedAt?: string }
+      >(metaKey(groupId, id));
+      if (!metaData && !(await storage.hasItem(dataKey(groupId, id)))) return null;
+
+      return {
+        id,
+        groupId,
+        meta: stripInternal(metaData),
+        createdAt: metaData?._createdAt
+          ? new Date(metaData._createdAt)
+          : undefined,
+        updatedAt: metaData?._updatedAt
+          ? new Date(metaData._updatedAt)
+          : undefined,
+      };
+    },
+
     async getData(groupId, id) {
       return await getStorage().getItemRaw<Buffer>(dataKey(groupId, id));
     },

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

@@ -6,7 +6,7 @@ import {
   createError,
 } from 'h3';
 import type { StoredFile } from '../../../runtime/types';
-import { useFileStorageProvider } from '../provider';
+import { headStoredFile, useFileStorageProvider } from '../provider';
 
 export type { StoredFile };
 
@@ -27,9 +27,14 @@ export interface SendStoredFileOptions {
 
 const DEFAULT_MAX_AGE = 60 * 60 * 24 * 365; // 1 year, matching the IPX route.
 
-/** The mtime the IPX route also uses: prefer `updatedAt`, fall back to `createdAt`. */
+/**
+ * The mtime the IPX route also uses: prefer `updatedAt`, fall back to
+ * `createdAt`. Truncated to whole seconds like HTTP dates, so an echoed
+ * `if-modified-since` compares equal instead of looking older.
+ */
 function fileMtime(file: StoredFile): Date | undefined {
-  return file.updatedAt ?? file.createdAt ?? undefined;
+  const mtime = file.updatedAt ?? file.createdAt;
+  return mtime ? new Date(Math.floor(mtime.getTime() / 1000) * 1000) : undefined;
 }
 
 /**
@@ -77,7 +82,9 @@ export async function sendStoredFile(
 ): Promise<Buffer | null> {
   const provider = useFileStorageProvider();
 
-  const file = await provider.get(groupId, id);
+  // Metadata only, so a 304 never reads the bytes (with providers that
+  // implement `head()`; otherwise `get()` already loaded them and are reused).
+  const file = await headStoredFile(provider, groupId, id);
   if (!file) {
     throw createError({ statusCode: 404, statusMessage: 'File not found' });
   }
@@ -97,8 +104,10 @@ export async function sendStoredFile(
   // Conditional request handling — answer 304 before touching the bytes.
   const ifNoneMatch = getRequestHeader(event, 'if-none-match');
   const ifModifiedSince = getRequestHeader(event, 'if-modified-since');
-  const notModified = etag
-    ? ifNoneMatch === etag
+  // RFC 9110: if-none-match takes precedence; if-modified-since applies only
+  // when it's absent.
+  const notModified = ifNoneMatch
+    ? !!etag && ifNoneMatch === etag
     : !!lastModified
       && !!ifModifiedSince
       && lastModified.getTime() <= Date.parse(ifModifiedSince);
@@ -121,7 +130,7 @@ export async function sendStoredFile(
     )
   );
 
-  const data = await provider.getData(groupId, id);
+  const data = file.data ?? (await provider.getData(groupId, id));
   if (!data) {
     throw createError({ statusCode: 404, statusMessage: 'File not found' });
   }

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

@@ -7,7 +7,7 @@ import type {
   ImageTransformOptions,
   ImageTransformResult,
 } from '../../../runtime/types';
-import { useFileStorageProvider } from '../provider';
+import { headStoredFile, useFileStorageProvider } from '../provider';
 import { transformImage } from './image';
 import { transformWithService, useImageService } from './image-service-runtime';
 
@@ -61,6 +61,15 @@ export const useFileStorage = () => {
     return await provider.get(groupId, id);
   }
 
+  /** Like {@link get} but without the bytes, when the provider supports it. */
+  async function head(
+    groupId: string,
+    id: string
+  ): Promise<StoredFile | null> {
+    const file = await headStoredFile(provider, groupId, id);
+    return file && { ...file, data: undefined };
+  }
+
   async function getData(
     groupId: string,
     id: string
@@ -154,6 +163,7 @@ export const useFileStorage = () => {
     upload,
     list,
     get,
+    head,
     getData,
     getMeta,
     updateMeta,

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

@@ -0,0 +1,94 @@
+import { consola } from 'consola';
+import type {
+  ImageTransformOptions,
+  ImageTransformResult,
+} from '../../../runtime/types';
+import { transformImage } from './image';
+
+export interface ThumbnailOptions extends ImageTransformOptions {
+  /** PDF page to render. Default: `1`. */
+  page?: number;
+}
+
+const DEFAULTS: ThumbnailOptions = {
+  width: 300,
+  height: 300,
+  fit: 'inside',
+  format: 'webp',
+  // A thumbnail shows the first frame; pass `animated: true` to keep animation.
+  animated: false,
+};
+
+const warned = new Set<string>();
+function warnOnce(key: string, message: string) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  consola.warn(message);
+}
+
+/** Whether an import failed because the package isn't installed (also when wrapped in `cause`). */
+function isMissingModule(error: unknown): boolean {
+  for (let e = error as { code?: string; message?: string; cause?: unknown } | undefined; e; e = e.cause as typeof e) {
+    if (e.code === 'ERR_MODULE_NOT_FOUND' || e.code === 'MODULE_NOT_FOUND') return true;
+    if (/Cannot find (?:module|package)|Failed to load url/i.test(String(e.message))) return true;
+  }
+  return false;
+}
+
+/** Render one PDF page to a PNG with `unpdf` (+ `@napi-rs/canvas` on Node). */
+async function renderPdfPage(data: Uint8Array, page: number, width: number): Promise<Buffer> {
+  const { renderPageAsImage } = await import('unpdf');
+  // pdf.js may transfer (detach) the buffer it's given; hand it a copy so the
+  // caller's bytes stay intact.
+  const png = await renderPageAsImage(new Uint8Array(data), page, {
+    canvasImport: () => import('@napi-rs/canvas'),
+    width,
+  });
+  return Buffer.from(png);
+}
+
+/**
+ * Generate a preview image for a stored file: images are resized with sharp,
+ * PDFs have a page (default: the first) rendered with `unpdf` and then resized.
+ *
+ * Returns `null` — never throws — when the type isn't supported, the input
+ * can't be decoded, or the optional dependencies aren't installed (`sharp`,
+ * plus `unpdf` and `@napi-rs/canvas` for PDFs; a warning is logged once).
+ *
+ * ```ts
+ * const thumb = await generateThumbnail(file.data, file.type, { width: 300, height: 200 })
+ * if (thumb) await storage.upload(group, thumb.data, { meta: { ...meta, mime: thumb.mime } })
+ * ```
+ */
+export async function generateThumbnail(
+  data: Buffer | Uint8Array,
+  mime: string,
+  options: ThumbnailOptions = {},
+): Promise<ImageTransformResult | null> {
+  const { page = 1, ...transform } = { ...DEFAULTS, ...options };
+  const type = mime.toLowerCase().split(';')[0]!.trim();
+
+  try {
+    if (type === 'application/pdf') {
+      // Render with headroom over the target box so the resize stays sharp.
+      const width = Math.min(2 * Math.max(transform.width ?? 0, transform.height ?? 0, 300), 4096);
+      const png = await renderPdfPage(data, page, width);
+      return await transformImage(png, transform);
+    }
+    if (type.startsWith('image/')) {
+      return await transformImage(data, transform);
+    }
+    return null;
+  }
+  catch (error) {
+    if (isMissingModule(error) || /optional peer dependency `sharp`/.test(String((error as Error)?.message))) {
+      warnOnce(
+        type,
+        type === 'application/pdf'
+          ? '[nuxt-filer] generateThumbnail: PDF previews need the optional dependencies `unpdf`, `@napi-rs/canvas` and `sharp`.'
+          : '[nuxt-filer] generateThumbnail: image previews need the optional dependency `sharp`.',
+      );
+    }
+    return null;
+  }
+}

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

@@ -0,0 +1,157 @@
+import {
+  type H3Event,
+  createError,
+  getRequestHeader,
+  readMultipartFormData,
+} from 'h3';
+
+/** A file read from a `multipart/form-data` request. */
+export interface UploadedFile {
+  /** The file's bytes. */
+  data: Buffer;
+  /** The client-supplied filename. */
+  name: string;
+  /** MIME type as sent by the client, `application/octet-stream` when missing. */
+  type: string;
+  /** Size in bytes. */
+  size: number;
+  /** The request's non-file form fields, e.g. `{ group: 'models' }`. */
+  fields: Record<string, string>;
+}
+
+export interface ReadUploadedFileOptions {
+  /**
+   * Accepted types, using the syntax of the HTML `accept` attribute plus a
+   * shorthand for families: an exact MIME type (`'image/png'`), a family
+   * (`'image'` or `'image/*'`), or an extension (`'.stl'`). Any match is
+   * enough. Default: anything.
+   */
+  types?: string[];
+  /** Max size per file: bytes, or a string like `'500KB'` / `'2MB'` / `'1GB'` (1024-based). */
+  maxSize?: number | string;
+  /** Form field holding the file(s). Default: `'file'`. */
+  field?: string;
+}
+
+export interface ReadUploadedFilesOptions extends ReadUploadedFileOptions {
+  /** Max number of files. Default: unlimited. */
+  max?: number;
+}
+
+const UNITS: Record<string, number> = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+
+/** Parse `'2MB'`-style sizes (1024-based); numbers are bytes. */
+export function parseSize(size: number | string): number {
+  if (typeof size === 'number') return size;
+  const match = size.trim().toUpperCase().match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)$/);
+  if (!match) throw new Error(`[nuxt-filer] invalid size "${size}" (use e.g. 500KB, 2MB, 1GB)`);
+  return Math.floor(Number(match[1]) * UNITS[match[2]!]!);
+}
+
+function formatSize(bytes: number): string {
+  for (const unit of ['GB', 'MB', 'KB'] as const) {
+    if (bytes >= UNITS[unit]! && bytes % UNITS[unit]! === 0) return `${bytes / UNITS[unit]!} ${unit}`;
+  }
+  return bytes >= UNITS.MB! ? `${(bytes / UNITS.MB!).toFixed(1)} MB` : `${bytes} B`;
+}
+
+/** Whether a file matches one of the accepted `types` (see {@link ReadUploadedFileOptions.types}). */
+export function matchesType(file: { name: string; type: string }, types: string[]): boolean {
+  const mime = file.type.toLowerCase();
+  const name = file.name.toLowerCase();
+  return types.some((raw) => {
+    const type = raw.trim().toLowerCase();
+    if (type.startsWith('.')) return name.endsWith(type);
+    if (type.endsWith('/*')) return mime.startsWith(type.slice(0, -1));
+    if (!type.includes('/')) return mime.startsWith(`${type}/`);
+    return mime === type;
+  });
+}
+
+// Generous per-part allowance for multipart boundaries and headers, so the
+// Content-Length precheck never rejects a request that fits the limit.
+const MULTIPART_OVERHEAD = 64 * 1024;
+
+async function readFiles(event: H3Event, options: ReadUploadedFilesOptions): Promise<UploadedFile[]> {
+  const field = options.field ?? 'file';
+  const maxSize = options.maxSize === undefined ? undefined : parseSize(options.maxSize);
+
+  // Reject obviously oversized requests before buffering the body.
+  if (maxSize !== undefined && options.max !== undefined) {
+    const length = Number(getRequestHeader(event, 'content-length'));
+    if (length > (maxSize + MULTIPART_OVERHEAD) * options.max) {
+      throw createError({ statusCode: 413, statusMessage: 'File too large', message: `File too large (max ${formatSize(maxSize)})` });
+    }
+  }
+
+  const parts = (await readMultipartFormData(event)) ?? [];
+  const fields: Record<string, string> = {};
+  for (const part of parts) {
+    if (part.name && part.filename === undefined) fields[part.name] = part.data.toString('utf8');
+  }
+
+  const files = parts
+    .filter((part) => part.name === field && part.filename)
+    .map((part): UploadedFile => ({
+      data: part.data,
+      name: part.filename!,
+      type: part.type || 'application/octet-stream',
+      size: part.data.length,
+      fields,
+    }));
+
+  if (!files.length) {
+    throw createError({ statusCode: 400, statusMessage: 'No file provided', message: `No file provided (expected form field "${field}")` });
+  }
+  if (options.max !== undefined && files.length > options.max) {
+    throw createError({ statusCode: 400, statusMessage: 'Too many files', message: `Too many files (max ${options.max})` });
+  }
+  for (const file of files) {
+    if (maxSize !== undefined && file.size > maxSize) {
+      throw createError({
+        statusCode: 413,
+        statusMessage: 'File too large',
+        message: `File "${file.name}" is too large (max ${formatSize(maxSize)})`,
+      });
+    }
+    if (options.types && !matchesType(file, options.types)) {
+      throw createError({
+        statusCode: 415,
+        statusMessage: 'Unsupported file type',
+        message: `File type of "${file.name}" is not allowed (allowed: ${options.types.join(', ')})`,
+      });
+    }
+  }
+  return files;
+}
+
+/**
+ * Read and validate a single uploaded file from a `multipart/form-data`
+ * request. Throws an H3 error — 400 when no file is present, 413 when it
+ * exceeds `maxSize`, 415 when its type isn't accepted — with a short
+ * `statusMessage` and a `message` naming the file and the limit.
+ *
+ * ```ts
+ * export default defineEventHandler(async (event) => {
+ *   const file = await readUploadedFile(event, { types: ['image'], maxSize: '5MB' })
+ *   const id = await useFileStorage().upload('avatars', file.data, {
+ *     meta: { name: file.name, mime: file.type, type: 'image', version: 1 },
+ *   })
+ *   return { id }
+ * })
+ * ```
+ */
+export async function readUploadedFile(
+  event: H3Event,
+  options: ReadUploadedFileOptions = {},
+): Promise<UploadedFile> {
+  return (await readFiles(event, { ...options, max: 1 }))[0]!;
+}
+
+/** Like {@link readUploadedFile}, for several files in the same form field. */
+export async function readUploadedFiles(
+  event: H3Event,
+  options: ReadUploadedFilesOptions = {},
+): Promise<UploadedFile[]> {
+  return readFiles(event, options);
+}

package/src/runtime/types.ts

@@ -152,6 +152,11 @@ export interface FileStorageProvider {
     meta?: FileMeta
   ): Promise<{ id: string }>;
   get(groupId: string, id: string): Promise<StoredFile | null>;
+  /**
+   * Like {@link get} but without reading the bytes (`data` is undefined).
+   * Optional: when a provider doesn't implement it, callers fall back to `get()`.
+   */
+  head?(groupId: string, id: string): Promise<StoredFile | null>;
   getData(groupId: string, id: string): Promise<Buffer | null>;
   getMeta(id: string): Promise<FileMeta | null>;
   list(groupId: string): Promise<StoredFile[]>;