nuxt-filer 0.0.16 → 0.0.17

package/README.md

@@ -9,7 +9,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 
 ## Features
 
-- **Pluggable provider architecture** — use the built-in unstorage provider or bring your own (Prisma, Drizzle, etc.)
+- **Pluggable provider architecture** — built-in unstorage (default), S3 and Drizzle providers, or bring your own
 - **File versioning** — built-in version tracking, latest-version filtering, and duplicate detection
 - **External file sync** — two-way sync with external systems (Jira, SharePoint, etc.) via optional provider interface
 - **Zero-config default** — works out of the box with local filesystem storage, no database required
@@ -32,7 +32,8 @@ npx nuxi module add nuxt-filer
 export default defineNuxtConfig({
   modules: ['nuxt-filer'],
   filer: {
-    // Nitro storage mount name (default: 'documents')
+    // Nitro storage mount name (default: 'documents'). Mounted on the local fs
+    // for every provider unless you configure it yourself under `nitro.storage`.
     storageName: 'documents',
     // Base path for fs-lite driver (default: '.data/documents')
     storagePath: '.data/documents',
@@ -192,7 +193,45 @@ filer: {
 },
 ```
 
-`@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration.
+`@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration. Both ipx 3 and ipx 4 (pulled in by `@nuxt/image` 2.1+) are supported.
+
+### External image service (imgproxy / standalone IPX)
+
+Image processing can run in a separate service instead of this server, so
+`sharp` and `ipx` aren't needed here and one service can serve many apps:
+
+```ts
+filer: {
+  image: {
+    service: 'imgproxy', // or 'ipx' for a standalone `npx ipx serve`; default 'local'
+  },
+},
+```
+
+```bash
+NUXT_FILER_IMAGE_BASE_URL=https://img.example.com
+NUXT_FILER_IMAGE_KEY=...           # imgproxy signing key + salt (hex); unsigned URLs when unset
+NUXT_FILER_IMAGE_SALT=...
+NUXT_FILER_IMAGE_SOURCE_URL=http://app:3000   # how the service reaches this app
+```
+
+- `<NuxtImg provider="filer">` works unchanged. The image route redirects to a
+  signed service URL, so the signing key never reaches the browser.
+- The service fetches originals from `/_filer-ipx/_/<groupId>/<fileId>`, which
+  serves the stored bytes. `sourceURL` is the origin it uses for that — e.g. the
+  app's address on a private Docker network. Without it, the request's origin
+  is used.
+- Upload-time transforms (`upload(..., { transform })`) go through the service
+  too: the original is staged under the `_filer-transform` group, the variant
+  is fetched, and the staged copy is removed. This requires `sourceURL`.
+  `transformImage()` itself still needs `sharp`.
+- imgproxy receives the IPX modifiers translated to its options (`w`, `h`,
+  `s`, `fit`, `enlarge`, `q`, `f`, `b`, `pos`, `blur`, `sharpen`, `rotate`);
+  modifiers without an equivalent are dropped. A standalone IPX gets them as-is.
+- imgproxy blocks loopback and private source addresses by default. If
+  `sourceURL` points at one, set `IMGPROXY_ALLOW_LOOPBACK_SOURCE_ADDRESSES` /
+  `IMGPROXY_ALLOW_PRIVATE_SOURCE_ADDRESSES`. A standalone IPX needs the source
+  host in `--domains`.
 
 ## Resumable uploads (tus)
 
@@ -323,9 +362,78 @@ export default defineNitroPlugin(() => {
 
 > `createS3Provider` requires the optional [`aws4fetch`](https://github.com/mhart/aws4fetch) peer dependency (`npm i aws4fetch`). Pass a custom `client` to use a different transport or to unit-test without network.
 
+## Drizzle (metadata in your database)
+
+`createDrizzleProvider` keeps file metadata in a table of your own
+[Drizzle](https://orm.drizzle.team) database and the bytes in a blob store —
+S3/R2 via `createS3Client()`, or any mounted Nitro storage. It uses only
+Drizzle's core query builder, so it works with every dialect and driver on
+Drizzle 0.36+ and v1.
+
+```ts
+// server/db/schema.ts
+import { pgTable, text, jsonb, timestamp, index } from 'drizzle-orm/pg-core'
+
+export const filerFiles = pgTable('filer_files', {
+  id: text('id').primaryKey(),
+  groupId: text('group_id').notNull(),
+  metadata: jsonb('metadata'),
+  createdAt: timestamp('created_at'), // optional
+  updatedAt: timestamp('updated_at'), // optional
+}, t => [index('filer_files_group_id_idx').on(t.groupId)])
+```
+
+```ts
+// server/plugins/file-provider.ts  (with `filer: { provider: 'custom' }`)
+import { db } from '../utils/db'
+import { filerFiles } from '../db/schema'
+
+export default defineNitroPlugin(() => {
+  const { s3 } = useRuntimeConfig()
+  setFileStorageProvider(createDrizzleProvider({
+    db,
+    table: filerFiles,
+    blobs: createS3Client({
+      accessKeyId: s3.accessKeyId,
+      secretAccessKey: s3.secretAccessKey,
+      endpoint: s3.endpoint,
+      bucket: s3.bucket,
+    }),
+    // or keep bytes on disk in the module's fs storage: blobs: 'documents'  (= `filer.storageName`)
+    // columns: { id: 'id', groupId: 'groupId', metadata: 'metadata', createdAt: 'createdAt', updatedAt: 'updatedAt' },
+  }))
+})
+```
+
+- `columns` maps to the table's schema property names, so an existing table can be used. `createdAt`/`updatedAt` are filled in when the table has them.
+- With a Postgres `jsonb` metadata column, `findByMeta()` (`@>`) and `update()` (`||` merge) run in the database — add a GIN index on `metadata` for large tables. Other column types and dialects filter and merge in JS.
+- Bytes are stored at `<groupId>/data/<id>`, the same layout as the S3 and unstorage providers, so moving metadata into a database keeps existing files readable.
+- Requires the optional `drizzle-orm` peer dependency.
+
+### Migrating from the unstorage provider
+
+Point `blobs` at the existing mount (`blobs: 'documents'`) so the bytes stay
+where they are, then copy the metadata sidecars into the table once —
+`importUnstorageMetadata` keeps ids and timestamps and skips rows that already
+exist, so re-running it is safe:
+
+```ts
+// server/tasks/filer/import.ts  (run with `nuxi task run filer:import`)
+import { db } from '../../utils/db'
+import { filerFiles } from '../../db/schema'
+
+export default defineTask({
+  meta: { description: 'Copy nuxt-filer metadata into the database' },
+  async run() {
+    const result = await importUnstorageMetadata({ from: 'documents', db, table: filerFiles })
+    return { result } // { imported, skipped }
+  },
+})
+```
+
 ## Custom Provider
 
-For advanced use cases (database-backed metadata, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
+For advanced use cases (other databases, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
 
 ```ts
 // nuxt.config.ts

package/dist/module.d.mts

@@ -12,6 +12,25 @@ interface FilerImageOptions {
     route?: string;
     /** Name to register the @nuxt/image provider under. Default: `filer`. */
     providerName?: string;
+    /**
+     * Where images are processed. `'local'` (default) runs IPX/sharp in this
+     * server. `'imgproxy'` or `'ipx'` (a standalone `ipx serve`) offload it: the
+     * image route redirects to the service, and upload-time transforms are
+     * fetched from it — so `sharp`/`ipx` aren't needed here.
+     */
+    service?: 'local' | 'imgproxy' | 'ipx';
+    /** Base URL of the image service. Runtime override: `NUXT_FILER_IMAGE_BASE_URL`. */
+    baseURL?: string;
+    /** imgproxy signing key (hex). Prefer `NUXT_FILER_IMAGE_KEY`. Unsigned URLs when unset. */
+    key?: string;
+    /** imgproxy signing salt (hex). Prefer `NUXT_FILER_IMAGE_SALT`. */
+    salt?: string;
+    /**
+     * Origin the service fetches originals from (e.g. `http://app:3000` on a
+     * private network). Defaults to the request origin; required for
+     * upload-time transforms. Runtime override: `NUXT_FILER_IMAGE_SOURCE_URL`.
+     */
+    sourceURL?: string;
 }
 interface FilerTusOptions {
     /** Enable the tus endpoint + composable. Defaults to `true` when the `tus` option is an object. */

package/dist/module.json

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

package/dist/module.mjs

@@ -43,6 +43,18 @@ const module = defineNuxtModule({
       {
         name: "createS3Provider",
         from: resolver.resolve("./runtime/server/providers/s3")
+      },
+      {
+        name: "createS3Client",
+        from: resolver.resolve("./runtime/server/providers/s3")
+      },
+      {
+        name: "createDrizzleProvider",
+        from: resolver.resolve("./runtime/server/providers/drizzle")
+      },
+      {
+        name: "importUnstorageMetadata",
+        from: resolver.resolve("./runtime/server/providers/drizzle")
       }
     ]);
     const typesSpecifier = "nuxt-filer/runtime/types";
@@ -92,12 +104,29 @@ const module = defineNuxtModule({
     const imageEnabled = options.image !== false && (imageOpt.enabled ?? true) !== false;
     const ipxRoute = (imageOpt.route ?? "/_filer-ipx").replace(/\/+$/, "");
     const providerName = imageOpt.providerName ?? "filer";
-    const shouldRegisterImage = imageEnabled && (imageOpt.enabled === "force" || hasNuxtModule("@nuxt/image"));
-    if (shouldRegisterImage) {
+    const imageService = imageEnabled ? imageOpt.service ?? "local" : "local";
+    if (imageService !== "local") {
+      const runtimeFiler = nuxt.options.runtimeConfig.filer ?? {};
+      runtimeFiler.image = defu(runtimeFiler.image, {
+        baseURL: imageOpt.baseURL ?? "",
+        key: imageOpt.key ?? "",
+        salt: imageOpt.salt ?? "",
+        sourceURL: imageOpt.sourceURL ?? ""
+      });
+      nuxt.options.runtimeConfig.filer = runtimeFiler;
       addServerHandler({
         route: `${ipxRoute}/**`,
-        handler: resolver.resolve("./runtime/server/handlers/ipx")
+        handler: resolver.resolve("./runtime/server/handlers/image-service")
       });
+    }
+    const shouldRegisterImage = imageEnabled && (imageOpt.enabled === "force" || hasNuxtModule("@nuxt/image"));
+    if (shouldRegisterImage) {
+      if (imageService === "local") {
+        addServerHandler({
+          route: `${ipxRoute}/**`,
+          handler: resolver.resolve("./runtime/server/handlers/ipx")
+        });
+      }
       const optionsWithImage = nuxt.options;
       const imageConfig = optionsWithImage.image ?? {};
       const providers = imageConfig.providers ?? {};
@@ -123,18 +152,21 @@ const module = defineNuxtModule({
         `export const storageName = ${JSON.stringify(options.storageName)};`,
         `export const storagePath = ${JSON.stringify(options.storagePath)};`
       ].join("\n");
-      nitroConfig.virtual["#nuxt-filer-image"] = `export const ipxRoute = ${JSON.stringify(ipxRoute)}`;
+      nitroConfig.virtual["#nuxt-filer-image"] = [
+        `export const ipxRoute = ${JSON.stringify(ipxRoute)};`,
+        `export const imageService = ${JSON.stringify(imageService)};`
+      ].join("\n");
       nitroConfig.virtual["#nuxt-filer-tus"] = [
         `export const tusRoute = ${JSON.stringify(tusRoute)};`,
         `export const tusStagingDir = ${JSON.stringify(tusStagingDir)};`,
         `export const tusMaxSize = ${JSON.stringify(tusOpt.maxSize ?? 0)};`,
         `export const tusExpiration = ${JSON.stringify(tusOpt.expiration ?? 0)};`
       ].join("\n");
+      nitroConfig.plugins = nitroConfig.plugins || [];
+      nitroConfig.plugins.push(
+        resolver.resolve("./runtime/server/plugins/default-storage")
+      );
       if (options.provider === "unstorage") {
-        nitroConfig.plugins = nitroConfig.plugins || [];
-        nitroConfig.plugins.push(
-          resolver.resolve("./runtime/server/plugins/default-storage")
-        );
         nitroConfig.plugins.push(
           resolver.resolve("./runtime/server/plugins/default-provider")
         );

package/dist/runtime/server/handlers/image-service.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Image route for an external service (imgproxy / standalone IPX). Same URL
+ * shape as the local IPX route — `<route>/<modifiers>/<groupId>/<id>` — so the
+ * `@nuxt/image` provider is unchanged:
+ *
+ * - `_` (no modifiers) serves the stored original. This is what the service
+ *   fetches as its source.
+ * - anything else redirects to the service, so signing keys stay server-side
+ *   and this server never loads sharp/IPX.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void | Buffer<ArrayBufferLike> | null>>;
+export default _default;

package/dist/runtime/server/handlers/image-service.js

@@ -0,0 +1,21 @@
+import { defineEventHandler, createError, getRequestURL, sendRedirect, setResponseHeader } from "h3";
+import { ipxRoute } from "#nuxt-filer-image";
+import { sendStoredFile } from "../utils/send.js";
+import { imageServiceURL, parseModifiers, sourceURL } from "../utils/image-service.js";
+import { useImageService } from "../utils/image-service-runtime.js";
+export default defineEventHandler(async (event) => {
+  const path = event.path.slice(ipxRoute.length).split("?")[0].replace(/^\/+/, "");
+  const [modifiers = "", ...segments] = path.split("/");
+  const parts = segments.filter(Boolean).map(decodeURIComponent);
+  if (parts.length < 2) {
+    throw createError({ statusCode: 404, statusMessage: "Image not found" });
+  }
+  const id = parts.pop();
+  const groupId = parts.join("/");
+  if (modifiers === "_") return sendStoredFile(event, groupId, id);
+  const config = useImageService();
+  const origin = config.sourceURL ?? getRequestURL(event).origin;
+  const url = await imageServiceURL(config, parseModifiers(modifiers), sourceURL(config, origin, groupId, id));
+  setResponseHeader(event, "cache-control", "public, max-age=86400");
+  return sendRedirect(event, url, 302);
+});

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

@@ -1,11 +1,17 @@
-import { defineEventHandler, useBase } from "h3";
-import { createIPX, createIPXH3Handler } from "ipx";
+import {
+  defineEventHandler,
+  sendWebResponse,
+  toWebRequest,
+  useBase
+} from "h3";
+import * as ipxModule from "ipx";
 import { ipxRoute } from "#nuxt-filer-image";
 import { useFileStorageProvider } from "../provider.js";
 function parseId(id) {
-  const lastSlash = id.lastIndexOf("/");
-  if (lastSlash <= 0 || lastSlash === id.length - 1) return null;
-  return [id.slice(0, lastSlash), id.slice(lastSlash + 1)];
+  const trimmed = id.replace(/^\/+/, "");
+  const lastSlash = trimmed.lastIndexOf("/");
+  if (lastSlash <= 0 || lastSlash === trimmed.length - 1) return null;
+  return [trimmed.slice(0, lastSlash), trimmed.slice(lastSlash + 1)];
 }
 const filerStorage = {
   name: "nuxt-filer",
@@ -18,7 +24,9 @@ const filerStorage = {
     if (!file) return void 0;
     const mtime = file.updatedAt ?? file.createdAt ?? /* @__PURE__ */ new Date();
     return {
-      mtime,
+      // HTTP dates have second precision; without truncating, the
+      // `if-modified-since` echo is always "older" than mtime and never 304s.
+      mtime: new Date(Math.floor(mtime.getTime() / 1e3) * 1e3),
       maxAge: 60 * 60 * 24 * 365
     };
   },
@@ -31,13 +39,23 @@ const filerStorage = {
     return data;
   }
 };
-let _handler = null;
-let _ipx = null;
-function getHandler() {
-  if (!_handler) {
-    _ipx = createIPX({ storage: filerStorage });
-    _handler = useBase(ipxRoute, createIPXH3Handler(_ipx));
+function createHandler() {
+  const ipx = ipxModule.createIPX({ storage: filerStorage });
+  const ipx4 = ipxModule;
+  if (ipx4.createIPXFetchHandler && ipx4.parseIPXURL) {
+    const { parseIPXURL } = ipx4;
+    const fetchHandler = ipx4.createIPXFetchHandler(ipx, {
+      parseURL(url) {
+        const parsed = new URL(url);
+        parsed.pathname = parsed.pathname.slice(ipxRoute.length) || "/";
+        return parseIPXURL(parsed.href);
+      }
+    });
+    return defineEventHandler(
+      async (event) => sendWebResponse(event, await fetchHandler(toWebRequest(event)))
+    );
   }
-  return _handler;
+  return useBase(ipxRoute, ipxModule.createIPXH3Handler(ipx));
 }
-export default defineEventHandler((event) => getHandler()(event));
+let _handler = null;
+export default defineEventHandler((event) => (_handler ??= createHandler())(event));

package/dist/runtime/server/plugins/default-storage.d.ts

@@ -2,7 +2,8 @@
  * Mount the default filesystem-backed storage for nuxt-filer. We mount
  * via a Nitro plugin rather than `nitroConfig.storage` so that our
  * custom fs driver is bundled with the plugin and there is no runtime
- * module resolution against the package's `dist/`.
+ * module resolution against the package's `dist/`. A mount the app already
+ * configured under the same name (`nitro.storage`) is left alone.
  */
 declare const _default: import("nitropack/types").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/plugins/default-storage.js

@@ -3,5 +3,7 @@ import { storageName, storagePath } from "#nuxt-filer-options";
 import fsDriver from "../drivers/fs.js";
 export default defineNitroPlugin(() => {
   const storage = useStorage();
+  const mounted = storage.getMount(storageName).base.replace(/:$/, "");
+  if (mounted === storageName.replace(/[:/]+/g, ":").replace(/:$/, "")) return;
   storage.mount(storageName, fsDriver({ base: storagePath }));
 });

package/dist/runtime/server/providers/drizzle.d.ts

@@ -0,0 +1,75 @@
+import type { Table } from 'drizzle-orm';
+import type { FileStorageProvider } from '../../../runtime/types.js';
+/**
+ * Where the drizzle provider keeps file bytes — the database only holds
+ * metadata. The {@link S3Client} from `createS3Client()` satisfies this, and a
+ * string is shorthand for a Nitro storage mount name.
+ */
+export interface BlobStore {
+    put(key: string, body: Buffer | Uint8Array, contentType?: string): Promise<void>;
+    get(key: string): Promise<Buffer | null>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * The slice of a Drizzle database the provider calls. Kept loose on purpose:
+ * Drizzle's per-dialect builders (pg/mysql/sqlite, v0.x and v1) don't share a
+ * common base type, so any `drizzle(...)` instance is accepted here.
+ */
+export interface DrizzleDatabase {
+    select: (...args: any[]) => any;
+    insert: (table: any) => any;
+    update: (table: any) => any;
+    delete: (table: any) => any;
+}
+export interface DrizzleProviderOptions {
+    /** Your Drizzle database instance (any dialect, any async or sync driver). */
+    db: DrizzleDatabase;
+    /** The table holding file metadata. */
+    table: Table;
+    /**
+     * Where file bytes are stored: a {@link BlobStore} (e.g. `createS3Client()`)
+     * or the name of a mounted Nitro storage.
+     */
+    blobs: BlobStore | string;
+    /** Schema property names of the columns used. Unset timestamps are optional. */
+    columns?: {
+        /** Default: `'id'`. */
+        id?: string;
+        /** Default: `'groupId'`. */
+        groupId?: string;
+        /** JSON column. Default: `'metadata'`. */
+        metadata?: string;
+        /** Set on insert when the table has it. Default: `'createdAt'`. */
+        createdAt?: string;
+        /** Set on insert/update when the table has it. Default: `'updatedAt'`. */
+        updatedAt?: string;
+    };
+}
+/**
+ * Drizzle-backed {@link FileStorageProvider}: metadata lives in a database
+ * table, bytes in a {@link BlobStore}. Uses only Drizzle's core query builder,
+ * which is unchanged between v0.x and v1.
+ *
+ * When the metadata column is Postgres `jsonb`, `findByMeta` and `update` run
+ * in the database (`@>` containment / `||` merge); other dialects filter and
+ * merge in JS.
+ */
+export declare function createDrizzleProvider(options: DrizzleProviderOptions): FileStorageProvider;
+export interface ImportUnstorageMetadataOptions {
+    /** Nitro storage mount the unstorage provider wrote to (e.g. `'documents'`). */
+    from: string;
+    db: DrizzleDatabase;
+    table: Table;
+    columns?: DrizzleProviderOptions['columns'];
+}
+/**
+ * One-off migration from the unstorage provider: copies its JSON metadata
+ * sidecars (`<groupId>:meta:<id>`) into the Drizzle table, keeping ids and
+ * timestamps. Bytes stay where they are — point `createDrizzleProvider`'s
+ * `blobs` at the same mount. Rows that already exist are skipped, so it is
+ * safe to re-run.
+ */
+export declare function importUnstorageMetadata(options: ImportUnstorageMetadataOptions): Promise<{
+    imported: number;
+    skipped: number;
+}>;