nuxt-filer 0.0.11 → 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.11",
+  "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/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.11",
+  "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/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;
+}