nuxt-filer 0.0.9 → 0.0.12

package/README.md

@@ -136,6 +136,30 @@ 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 |
 
+### 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.
+
+```ts
+// server/api/files/[groupId]/[id].get.ts
+export default defineEventHandler((event) => {
+  const { groupId, id } = getRouterParams(event)
+  return sendStoredFile(event, groupId, id) // 404 if missing
+})
+```
+
+It sets `content-type` from `meta.mime`, a `content-disposition` filename from `meta.name`, and `cache-control` / `last-modified` / `etag`, honoring `if-modified-since` / `if-none-match` (`304`) — just like the IPX route. `HEAD` requests get the headers without a body.
+
+```ts
+sendStoredFile(event, groupId, id, {
+  disposition: 'attachment', // force a download ('inline' is the default)
+  filename: 'invoice-2026.pdf', // override the download name (default: meta.name)
+  maxAge: 3600, // cache-control max-age in seconds (default: 1 year; 0 = no-cache)
+})
+```
+
+`sendStoredFile` is auto-imported in your server routes — no need to import it.
+
 ## `@nuxt/image` Integration
 
 If `@nuxt/image` is installed alongside `nuxt-filer`, the module automatically registers a `filer` image provider and an IPX endpoint that pulls bytes from your storage provider, runs them through Sharp, and returns the result.

package/dist/module.json

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

package/dist/module.mjs

@@ -22,6 +22,10 @@ const module = defineNuxtModule({
       {
         name: "transformImage",
         from: resolver.resolve("./runtime/server/utils/image")
+      },
+      {
+        name: "sendStoredFile",
+        from: resolver.resolve("./runtime/server/utils/send")
       }
     ]);
     const providerSpecifier = resolver.resolve("./runtime/server/provider");

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/send.d.ts

@@ -0,0 +1,33 @@
+import { type H3Event } from 'h3';
+import type { StoredFile } from '../../../runtime/types.js';
+export type { StoredFile };
+export interface SendStoredFileOptions {
+    /**
+     * `content-disposition` type. `'inline'` (the default) lets the browser
+     * render the file in place; `'attachment'` forces a download.
+     */
+    disposition?: 'inline' | 'attachment';
+    /** Override the download filename. Defaults to the stored `meta.name`. */
+    filename?: string;
+    /**
+     * `cache-control` max-age in seconds. Default: one year — matching the IPX
+     * route. Pass `0` to mark the response uncacheable.
+     */
+    maxAge?: number;
+}
+/**
+ * Stream a stored file back through an H3 event with the same HTTP revalidation
+ * story as the IPX image route: `content-type` from `meta.mime`, a
+ * `content-disposition` filename from `meta.name`, and
+ * `cache-control` / `last-modified` / `etag` honoring `if-modified-since` /
+ * `if-none-match` (304). Throws a 404 when the file does not exist.
+ *
+ * ```ts
+ * // server/api/files/[groupId]/[id].get.ts
+ * export default defineEventHandler((event) => {
+ *   const { groupId, id } = getRouterParams(event)
+ *   return sendStoredFile(event, groupId, id)
+ * })
+ * ```
+ */
+export declare function sendStoredFile(event: H3Event, groupId: string, id: string, options?: SendStoredFileOptions): Promise<Buffer | null>;

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

@@ -0,0 +1,64 @@
+import {
+  getRequestHeader,
+  setResponseHeader,
+  setResponseStatus,
+  createError
+} from "h3";
+import { useFileStorageProvider } from "../provider.js";
+const DEFAULT_MAX_AGE = 60 * 60 * 24 * 365;
+function fileMtime(file) {
+  return file.updatedAt ?? file.createdAt ?? void 0;
+}
+function cacheValidators(file) {
+  const mtime = fileMtime(file);
+  if (!mtime) return {};
+  return { etag: `W/"${mtime.getTime().toString(16)}"`, lastModified: mtime };
+}
+function contentDisposition(type, name) {
+  const asciiName = name.replace(/[^\x20-\x7E]|["\\]/g, "_");
+  return `${type}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+export async function sendStoredFile(event, groupId, id, options = {}) {
+  const provider = useFileStorageProvider();
+  const file = await provider.get(groupId, id);
+  if (!file) {
+    throw createError({ statusCode: 404, statusMessage: "File not found" });
+  }
+  const maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+  const { etag, lastModified } = cacheValidators(file);
+  setResponseHeader(
+    event,
+    "cache-control",
+    maxAge > 0 ? `public, max-age=${maxAge}` : "no-cache"
+  );
+  if (etag) setResponseHeader(event, "etag", etag);
+  if (lastModified)
+    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);
+  if (notModified) {
+    setResponseStatus(event, 304);
+    return null;
+  }
+  setResponseHeader(
+    event,
+    "content-type",
+    file.meta.mime || "application/octet-stream"
+  );
+  setResponseHeader(
+    event,
+    "content-disposition",
+    contentDisposition(
+      options.disposition ?? "inline",
+      options.filename ?? file.meta.name
+    )
+  );
+  const data = await provider.getData(groupId, id);
+  if (!data) {
+    throw createError({ statusCode: 404, statusMessage: "File not found" });
+  }
+  setResponseHeader(event, "content-length", data.length);
+  if (event.method === "HEAD") return null;
+  return data;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
@@ -36,17 +36,6 @@
     "dist",
     "src/runtime"
   ],
-  "scripts": {
-    "prepack": "nuxt-module-build build",
-    "dev": "npm run dev:prepare && nuxi dev playground",
-    "dev:build": "nuxi build playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
-    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "test:watch": "vitest watch",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
-  },
   "dependencies": {
     "@nuxt/kit": "^4.4.2",
     "consola": "^3.4.2",
@@ -85,11 +74,14 @@
       "optional": true
     }
   },
-  "packageManager": "pnpm@10.33.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ]
+  "scripts": {
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
   }
-}
+}

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/send.ts

@@ -0,0 +1,135 @@
+import {
+  type H3Event,
+  getRequestHeader,
+  setResponseHeader,
+  setResponseStatus,
+  createError,
+} from 'h3';
+import type { StoredFile } from '../../../runtime/types';
+import { useFileStorageProvider } from '../provider';
+
+export type { StoredFile };
+
+export interface SendStoredFileOptions {
+  /**
+   * `content-disposition` type. `'inline'` (the default) lets the browser
+   * render the file in place; `'attachment'` forces a download.
+   */
+  disposition?: 'inline' | 'attachment';
+  /** Override the download filename. Defaults to the stored `meta.name`. */
+  filename?: string;
+  /**
+   * `cache-control` max-age in seconds. Default: one year — matching the IPX
+   * route. Pass `0` to mark the response uncacheable.
+   */
+  maxAge?: number;
+}
+
+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`. */
+function fileMtime(file: StoredFile): Date | undefined {
+  return file.updatedAt ?? file.createdAt ?? undefined;
+}
+
+/**
+ * Build a weak validator from the file's mtime so revalidation can be answered
+ * without reading the bytes back. Mirrors the IPX route, which keys its etag /
+ * last-modified off the same mtime.
+ */
+function cacheValidators(file: StoredFile): {
+  etag?: string;
+  lastModified?: Date;
+} {
+  const mtime = fileMtime(file);
+  if (!mtime) return {};
+  return { etag: `W/"${mtime.getTime().toString(16)}"`, lastModified: mtime };
+}
+
+/** RFC 6266 `content-disposition` value with an ASCII fallback + UTF-8 form. */
+function contentDisposition(type: string, name: string): string {
+  // Strip anything outside printable ASCII (plus quote/backslash) for the
+  // legacy `filename=`; the `filename*=` form carries the real UTF-8 name.
+  const asciiName = name.replace(/[^\x20-\x7E]|["\\]/g, '_');
+  return `${type}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+}
+
+/**
+ * Stream a stored file back through an H3 event with the same HTTP revalidation
+ * story as the IPX image route: `content-type` from `meta.mime`, a
+ * `content-disposition` filename from `meta.name`, and
+ * `cache-control` / `last-modified` / `etag` honoring `if-modified-since` /
+ * `if-none-match` (304). Throws a 404 when the file does not exist.
+ *
+ * ```ts
+ * // server/api/files/[groupId]/[id].get.ts
+ * export default defineEventHandler((event) => {
+ *   const { groupId, id } = getRouterParams(event)
+ *   return sendStoredFile(event, groupId, id)
+ * })
+ * ```
+ */
+export async function sendStoredFile(
+  event: H3Event,
+  groupId: string,
+  id: string,
+  options: SendStoredFileOptions = {}
+): Promise<Buffer | null> {
+  const provider = useFileStorageProvider();
+
+  const file = await provider.get(groupId, id);
+  if (!file) {
+    throw createError({ statusCode: 404, statusMessage: 'File not found' });
+  }
+
+  const maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
+  const { etag, lastModified } = cacheValidators(file);
+
+  setResponseHeader(
+    event,
+    'cache-control',
+    maxAge > 0 ? `public, max-age=${maxAge}` : 'no-cache'
+  );
+  if (etag) setResponseHeader(event, 'etag', etag);
+  if (lastModified)
+    setResponseHeader(event, 'last-modified', lastModified.toUTCString());
+
+  // 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
+    : !!lastModified
+      && !!ifModifiedSince
+      && lastModified.getTime() <= Date.parse(ifModifiedSince);
+  if (notModified) {
+    setResponseStatus(event, 304);
+    return null;
+  }
+
+  setResponseHeader(
+    event,
+    'content-type',
+    file.meta.mime || 'application/octet-stream'
+  );
+  setResponseHeader(
+    event,
+    'content-disposition',
+    contentDisposition(
+      options.disposition ?? 'inline',
+      options.filename ?? file.meta.name
+    )
+  );
+
+  const data = await provider.getData(groupId, id);
+  if (!data) {
+    throw createError({ statusCode: 404, statusMessage: 'File not found' });
+  }
+
+  setResponseHeader(event, 'content-length', data.length);
+
+  // HEAD requests get the full header set but no body.
+  if (event.method === 'HEAD') return null;
+
+  return data;
+}