nuxt-filer 0.0.15 → 0.0.16

package/README.md

@@ -17,6 +17,7 @@ File storage module for Nuxt. Provides a server-side `useFileStorage()` composab
 - **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
+- **Resumable uploads (tus)** — opt-in [tus](https://tus.io) endpoint backed by `@tus/server`, a client-side `useTusUpload()` composable, and `useTusStaging().promote()` to move finished uploads into the file storage
 
 ## Quick Setup
 
@@ -193,6 +194,102 @@ filer: {
 
 `@nuxt/image` and `ipx` are declared as optional peer dependencies — they only need to be installed if you want to use this integration.
 
+## Resumable uploads (tus)
+
+Large or flaky-network uploads can use the [tus protocol](https://tus.io)
+instead of a single multipart POST. Uploads are staged chunk-by-chunk into a
+local directory (survives connection drops and page reloads), then *promoted*
+into the regular file storage by one of your own server routes — which is
+where you enforce auth and attach domain metadata.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-filer'],
+  filer: {
+    tus: {
+      enabled: true,
+      route: '/_filer-tus',            // default
+      stagingDir: '.data/tus',         // default
+      maxSize: 500 * 1024 * 1024,      // optional, bytes
+      expiration: 24 * 60 * 60 * 1000, // optional: purge stale staged uploads
+    },
+  },
+})
+```
+
+Client side, the auto-imported `useTusUpload()` composable wraps
+[`tus-js-client`](https://github.com/tus/tus-js-client) with reactive state:
+
+```vue
+<script setup lang="ts">
+const tus = useTusUpload({
+  metadata: (file) => ({ comment: 'from the web app' }), // extra tus metadata
+  // cleanupOnPageHide: true,  // sendBeacon-delete staged uploads on close
+})
+
+function onSelect(e: Event) {
+  tus.add(Array.from((e.target as HTMLInputElement).files ?? []))
+}
+
+async function save() {
+  for (const item of tus.completed.value) {
+    await $fetch('/api/documents/finalize', {
+      method: 'POST',
+      body: { tusId: item.tusId, name: item.file.name },
+    })
+  }
+  tus.clear()
+}
+</script>
+```
+
+Each entry in `tus.items` tracks `progress`, `complete`, `tusId`, and `error`;
+`tus.remove(name)` aborts and deletes a staged upload, `tus.cancel()` discards
+everything. Interrupted uploads resume automatically (retry backoff, restart
+on `online`, and — via the tus fingerprint — across page reloads).
+
+Server side, promote a finished upload into the file storage:
+
+```ts
+// server/api/documents/finalize.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+
+  const { id, meta } = await useTusStaging().promote(body.tusId, 'my-group', {
+    meta: { type: 'document' },        // merged over tus filename/filetype
+    // transform: { width: 1600 },     // optional sharp processing
+  })
+
+  return { id, meta }
+})
+```
+
+`useTusStaging()` also exposes `info()`, `read()`, and `remove()` for staged
+uploads. To protect or customize the endpoint itself (auth, upload hooks, a
+different datastore), configure the underlying `@tus/server` from a Nitro
+plugin — the server is created lazily on the first request:
+
+```ts
+// server/plugins/tus.ts
+export default defineNitroPlugin(() => {
+  setTusServerOptions({
+    async onIncomingRequest(req) {
+      // throw { status_code: 401, body: 'Unauthorized' } to reject
+    },
+  })
+})
+```
+
+Notes:
+
+- The endpoint handles the full tus lifecycle (create/HEAD/PATCH/DELETE); a
+  `POST <route>/cleanup` sub-route accepts `{ tusIds: string[] }` from
+  `navigator.sendBeacon` for page-close cleanup (used by `cleanupOnPageHide`).
+- Staging uses `@tus/file-store` on the local filesystem, independent of the
+  configured storage provider — promotion works with any provider, including
+  S3 and custom ones.
+
 ## S3 storage
 
 For durable object storage (AWS S3, Cloudflare R2, MinIO, …) use the built-in

package/dist/module.d.mts

@@ -13,6 +13,21 @@ interface FilerImageOptions {
     /** Name to register the @nuxt/image provider under. Default: `filer`. */
     providerName?: string;
 }
+interface FilerTusOptions {
+    /** Enable the tus endpoint + composable. Defaults to `true` when the `tus` option is an object. */
+    enabled?: boolean;
+    /** Base route of the tus endpoint. Default: `/_filer-tus`. */
+    route?: string;
+    /** Directory where in-progress uploads are staged. Default: `.data/tus`. */
+    stagingDir?: string;
+    /** Max upload size in bytes. Default: unlimited. */
+    maxSize?: number;
+    /**
+     * Staged uploads older than this (ms) are expired: reported to clients via
+     * `Upload-Expires` and purged periodically. Default: never expire.
+     */
+    expiration?: number;
+}
 interface ModuleOptions {
     /** Nitro storage mount name for binary file data. Default: 'documents' */
     storageName?: string;
@@ -22,8 +37,10 @@ interface ModuleOptions {
     provider?: 'unstorage' | 'custom';
     /** @nuxt/image integration. Set to `false` to disable, or pass an object to override defaults. */
     image?: boolean | FilerImageOptions;
+    /** Resumable uploads via the tus protocol. Opt-in: pass `true` or an options object. */
+    tus?: boolean | FilerTusOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
 export { _default as default };
-export type { FilerImageOptions, ModuleOptions };
+export type { FilerImageOptions, FilerTusOptions, ModuleOptions };

package/dist/module.json

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

package/dist/module.mjs

@@ -1,5 +1,6 @@
-import { defineNuxtModule, createResolver, addServerImports, addImports, hasNuxtModule, addServerHandler, installModule } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addServerImports, addImports, addServerHandler, hasNuxtModule, installModule } from '@nuxt/kit';
 import { consola } from 'consola';
+import { defu } from 'defu';
 
 const module = defineNuxtModule({
   meta: {
@@ -10,7 +11,8 @@ const module = defineNuxtModule({
     storageName: "documents",
     storagePath: ".data/documents",
     provider: "unstorage",
-    image: true
+    image: true,
+    tus: false
   },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url);
@@ -56,8 +58,36 @@ const module = defineNuxtModule({
       },
       { name: "ImageFormat", from: typesSpecifier, type: true },
       { name: "ImageTransformOptions", from: typesSpecifier, type: true },
-      { name: "ImageTransformResult", from: typesSpecifier, type: true }
+      { name: "ImageTransformResult", from: typesSpecifier, type: true },
+      { name: "TusUploadState", from: typesSpecifier, type: true },
+      { name: "UseTusUploadOptions", from: typesSpecifier, type: true },
+      { name: "TusPromoteOptions", from: typesSpecifier, type: true }
     ]);
+    const tusOpt = typeof options.tus === "object" && options.tus !== null ? options.tus : {};
+    const tusEnabled = options.tus === true || typeof options.tus === "object" && options.tus !== null && tusOpt.enabled !== false;
+    const tusRoute = (tusOpt.route ?? "/_filer-tus").replace(/\/+$/, "");
+    const tusStagingDir = tusOpt.stagingDir ?? ".data/tus";
+    if (tusEnabled) {
+      const tusHandler = resolver.resolve("./runtime/server/handlers/tus");
+      addServerHandler({ route: tusRoute, handler: tusHandler });
+      addServerHandler({ route: `${tusRoute}/**`, handler: tusHandler });
+      const tusUtilsSpecifier = resolver.resolve("./runtime/server/utils/tus");
+      addServerImports([
+        { name: "useTusServer", from: tusUtilsSpecifier },
+        { name: "setTusServerOptions", from: tusUtilsSpecifier },
+        { name: "useTusStaging", from: tusUtilsSpecifier }
+      ]);
+      addImports([
+        {
+          name: "useTusUpload",
+          from: resolver.resolve("./runtime/composables/tus")
+        }
+      ]);
+      nuxt.options.runtimeConfig.public.filer = defu(
+        nuxt.options.runtimeConfig.public.filer,
+        { tusRoute }
+      );
+    }
     const imageOpt = typeof options.image === "object" && options.image !== null ? options.image : {};
     const imageEnabled = options.image !== false && (imageOpt.enabled ?? true) !== false;
     const ipxRoute = (imageOpt.route ?? "/_filer-ipx").replace(/\/+$/, "");
@@ -68,7 +98,8 @@ const module = defineNuxtModule({
         route: `${ipxRoute}/**`,
         handler: resolver.resolve("./runtime/server/handlers/ipx")
       });
-      const imageConfig = nuxt.options.image ?? {};
+      const optionsWithImage = nuxt.options;
+      const imageConfig = optionsWithImage.image ?? {};
       const providers = imageConfig.providers ?? {};
       providers[providerName] = {
         name: providerName,
@@ -76,7 +107,7 @@ const module = defineNuxtModule({
         options: { baseURL: ipxRoute }
       };
       imageConfig.providers = providers;
-      nuxt.options.image = imageConfig;
+      optionsWithImage.image = imageConfig;
       const imageAlreadyLoaded = nuxt.options._installedModules?.some((m) => m.meta?.name === "@nuxt/image");
       if (imageAlreadyLoaded) {
         await installModule("@nuxt/image");
@@ -93,6 +124,12 @@ const module = defineNuxtModule({
         `export const storagePath = ${JSON.stringify(options.storagePath)};`
       ].join("\n");
       nitroConfig.virtual["#nuxt-filer-image"] = `export const ipxRoute = ${JSON.stringify(ipxRoute)}`;
+      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");
       if (options.provider === "unstorage") {
         nitroConfig.plugins = nitroConfig.plugins || [];
         nitroConfig.plugins.push(

package/dist/runtime/composables/tus.d.ts

@@ -0,0 +1,18 @@
+import type { TusUploadState, UseTusUploadOptions } from '../types.js';
+export type { TusUploadState, UseTusUploadOptions };
+/**
+ * Resumable uploads against the module's tus endpoint. Files are staged on
+ * the server; move them into the file storage afterwards with
+ * `useTusStaging().promote()` from one of your own server routes.
+ */
+export declare function useTusUpload(options?: UseTusUploadOptions): {
+    endpoint: string;
+    items: Record<string, TusUploadState>;
+    uploading: import("vue").ComputedRef<boolean>;
+    completed: import("vue").ComputedRef<TusUploadState[]>;
+    start: (file: File) => Promise<TusUploadState>;
+    add: (files: File | File[]) => void;
+    remove: (file: File | string) => Promise<void>;
+    clear: () => void;
+    cancel: () => Promise<void>;
+};

package/dist/runtime/composables/tus.js

@@ -0,0 +1,137 @@
+import { computed, reactive, getCurrentScope, onScopeDispose } from "vue";
+import { useRuntimeConfig } from "nuxt/app";
+import { Upload as TusUpload } from "tus-js-client";
+const DEFAULT_RETRY_DELAYS = [0, 3e3, 5e3, 1e4, 2e4];
+export function useTusUpload(options = {}) {
+  const runtimeConfig = useRuntimeConfig();
+  const endpoint = options.endpoint ?? runtimeConfig.public.filer?.tusRoute ?? "/_filer-tus";
+  const items = reactive({});
+  const instances = /* @__PURE__ */ new Map();
+  const uploading = computed(
+    () => Object.values(items).some((item) => !item.complete && !item.error)
+  );
+  const completed = computed(
+    () => Object.values(items).filter((item) => item.complete)
+  );
+  function captureUploadUrl(state, upload) {
+    if (upload.url && !state.tusId) {
+      state.uploadUrl = upload.url;
+      state.tusId = upload.url.split("/").pop();
+    }
+  }
+  async function start(file) {
+    const key = file.name;
+    const state = { file, progress: 0, complete: false };
+    items[key] = state;
+    const upload = new TusUpload(file, {
+      endpoint,
+      retryDelays: options.retryDelays ?? DEFAULT_RETRY_DELAYS,
+      chunkSize: options.chunkSize,
+      removeFingerprintOnSuccess: true,
+      metadata: {
+        filename: file.name,
+        filetype: file.type,
+        ...options.metadata?.(file)
+      },
+      onError(error) {
+        const item = items[key];
+        if (!item) return;
+        item.error = error instanceof Error ? error.message : String(error);
+        options.onError?.(file, error);
+      },
+      onProgress(bytesUploaded, bytesTotal) {
+        const item = items[key];
+        if (!item) return;
+        item.progress = bytesTotal ? bytesUploaded / bytesTotal * 100 : 0;
+        captureUploadUrl(item, upload);
+      },
+      onSuccess() {
+        const item = items[key];
+        if (!item) return;
+        captureUploadUrl(item, upload);
+        item.progress = 100;
+        item.complete = true;
+        options.onSuccess?.(file, item);
+      }
+    });
+    instances.set(key, upload);
+    if (options.resume !== false) {
+      const previous = await upload.findPreviousUploads().catch(() => []);
+      if (previous[0]) upload.resumeFromPreviousUpload(previous[0]);
+    }
+    upload.start();
+    return state;
+  }
+  function add(files) {
+    for (const file of Array.isArray(files) ? files : [files]) {
+      if (!items[file.name]) void start(file);
+    }
+  }
+  async function remove(file) {
+    const key = typeof file === "string" ? file : file.name;
+    const state = items[key];
+    const upload = instances.get(key);
+    instances.delete(key);
+    Reflect.deleteProperty(items, key);
+    if (upload) {
+      await upload.abort(true).catch(() => {
+      });
+    } else if (state?.uploadUrl) {
+      await fetch(state.uploadUrl, {
+        method: "DELETE",
+        headers: { "Tus-Resumable": "1.0.0" }
+      }).catch(() => {
+      });
+    }
+  }
+  function clear() {
+    for (const upload of instances.values()) {
+      void upload.abort().catch(() => {
+      });
+    }
+    instances.clear();
+    for (const key of Object.keys(items)) Reflect.deleteProperty(items, key);
+  }
+  async function cancel() {
+    await Promise.allSettled(Object.keys(items).map((key) => remove(key)));
+  }
+  if (import.meta.client) {
+    const onOnline = () => {
+      for (const [key, upload] of instances) {
+        const item = items[key];
+        if (item && !item.complete) {
+          item.error = void 0;
+          upload.start();
+        }
+      }
+    };
+    const onPageHide = () => {
+      if (!options.cleanupOnPageHide) return;
+      const tusIds = Object.values(items).map((item) => item.tusId).filter((id) => !!id);
+      if (tusIds.length === 0) return;
+      navigator.sendBeacon(
+        `${endpoint}/cleanup`,
+        new Blob([JSON.stringify({ tusIds })], { type: "application/json" })
+      );
+    };
+    window.addEventListener("online", onOnline);
+    window.addEventListener("pagehide", onPageHide);
+    if (getCurrentScope()) {
+      onScopeDispose(() => {
+        window.removeEventListener("online", onOnline);
+        window.removeEventListener("pagehide", onPageHide);
+      });
+    }
+  }
+  return {
+    endpoint,
+    items,
+    uploading,
+    completed,
+    start,
+    add,
+    remove,
+    clear,
+    cancel
+  };
+}

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

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Response | null>>;
+export default _default;

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

@@ -0,0 +1,36 @@
+import {
+  defineEventHandler,
+  toWebRequest,
+  readBody,
+  setResponseStatus,
+  createError
+} from "h3";
+import { tusRoute } from "#nuxt-filer-tus";
+import { useTusServer, useTusStaging, isSafeTusId } from "../utils/tus.js";
+async function handleCleanupBeacon(event) {
+  const body = await readBody(event).catch(() => null);
+  const tusIds = Array.isArray(body?.tusIds) ? body.tusIds.filter(isSafeTusId).slice(0, 100) : [];
+  const hook = useTusServer().options.onIncomingRequest;
+  if (hook) {
+    const request = toWebRequest(event);
+    for (const tusId of tusIds) {
+      try {
+        await hook(request, tusId);
+      } catch (error) {
+        const status = error.status_code ?? error.statusCode ?? 500;
+        throw createError({ statusCode: status, statusMessage: "Cleanup rejected" });
+      }
+    }
+  }
+  const staging = useTusStaging();
+  await Promise.allSettled(tusIds.map((id) => staging.remove(id)));
+  setResponseStatus(event, 204);
+  return null;
+}
+export default defineEventHandler(async (event) => {
+  const pathname = event.path.split("?")[0];
+  if (event.method === "POST" && pathname === `${tusRoute}/cleanup`) {
+    return handleCleanupBeacon(event);
+  }
+  return useTusServer().handleWeb(toWebRequest(event));
+});

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

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 async function mapWithConcurrency(items, limit, fn) {
-  const results = new Array(items.length);
+  const results = Array.from({ length: items.length });
   let next = 0;
   const worker = async () => {
     while (next < items.length) {

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

@@ -0,0 +1,33 @@
+import { Server, type ServerOptions, type DataStore, type Upload } from '@tus/server';
+import type { FileMeta, TusPromoteOptions } from '../../../runtime/types.js';
+export type { TusPromoteOptions };
+/**
+ * Everything of `ServerOptions` except `path` (owned by the module config)
+ * can be customized, plus the datastore itself. Note that `useTusStaging()`
+ * requires a datastore with a `read()` method (like the default FileStore).
+ */
+export type TusServerUserOptions = Partial<Omit<ServerOptions, 'path'>> & {
+    datastore?: DataStore;
+};
+/**
+ * Configure the tus server (auth via `onIncomingRequest`, `onUploadFinish`,
+ * a custom datastore, ...). Must be called before the first upload request —
+ * a Nitro plugin is the right place.
+ */
+export declare function setTusServerOptions(options: TusServerUserOptions): void;
+export declare function useTusServer(): Server;
+/** Guards datastore ids used in file paths against traversal. */
+export declare function isSafeTusId(id: unknown): id is string;
+/**
+ * Work with uploads staged by the tus endpoint: inspect, read, remove, or
+ * `promote()` them into the regular file storage.
+ */
+export declare function useTusStaging(): {
+    info: (tusId: string) => Promise<Upload | null>;
+    read: (tusId: string) => Promise<Buffer | null>;
+    remove: (tusId: string) => Promise<boolean>;
+    promote: (tusId: string, groupId: string, options?: TusPromoteOptions) => Promise<{
+        id: string;
+        meta: FileMeta;
+    }>;
+};

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

@@ -0,0 +1,132 @@
+import { createError } from "h3";
+import { defu } from "defu";
+import { consola } from "consola";
+import {
+  Server
+} from "@tus/server";
+import { FileStore } from "@tus/file-store";
+import { tusRoute, tusStagingDir, tusMaxSize, tusExpiration } from "#nuxt-filer-tus";
+import { useFileStorage } from "./storage.js";
+let userOptions = {};
+let server;
+let datastore;
+let expirationTimer;
+export function setTusServerOptions(options) {
+  if (server) {
+    consola.warn(
+      "nuxt-filer: setTusServerOptions() called after the tus server was created \u2014 the options are ignored. Call it from a Nitro plugin instead."
+    );
+    return;
+  }
+  userOptions = options;
+}
+function useTusDatastore() {
+  if (!datastore) {
+    datastore = userOptions.datastore ?? new FileStore({
+      directory: tusStagingDir,
+      expirationPeriodInMilliseconds: tusExpiration > 0 ? tusExpiration : void 0
+    });
+  }
+  return datastore;
+}
+export function useTusServer() {
+  if (!server) {
+    const { datastore: _datastore, ...serverOptions } = userOptions;
+    server = new Server({
+      path: tusRoute,
+      respectForwardedHeaders: true,
+      maxSize: tusMaxSize > 0 ? tusMaxSize : void 0,
+      datastore: useTusDatastore(),
+      ...serverOptions
+    });
+    if (tusExpiration > 0 && !expirationTimer) {
+      const instance = server;
+      expirationTimer = setInterval(
+        () => instance.cleanUpExpiredUploads().catch(() => {
+        }),
+        Math.min(tusExpiration, 60 * 60 * 1e3)
+      );
+      expirationTimer.unref?.();
+    }
+  }
+  return server;
+}
+export function isSafeTusId(id) {
+  return typeof id === "string" && id.length > 0 && id.length <= 255 && !id.includes("/") && !id.includes("\\") && !id.includes("..");
+}
+export function useTusStaging() {
+  const store = useTusDatastore();
+  async function info(tusId) {
+    if (!isSafeTusId(tusId)) return null;
+    try {
+      return await store.getUpload(tusId);
+    } catch {
+      return null;
+    }
+  }
+  async function read(tusId) {
+    if (!isSafeTusId(tusId)) return null;
+    const readable = store;
+    if (typeof readable.read !== "function") {
+      throw new TypeError(
+        "nuxt-filer: the configured tus datastore does not support read() \u2014 useTusStaging() requires a FileStore-compatible datastore"
+      );
+    }
+    try {
+      const chunks = [];
+      for await (const chunk of readable.read(tusId)) {
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    } catch {
+      return null;
+    }
+  }
+  async function remove(tusId) {
+    if (!isSafeTusId(tusId)) return false;
+    try {
+      await store.remove(tusId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async function promote(tusId, groupId, options = {}) {
+    const upload = await info(tusId);
+    if (!upload) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `No staged tus upload found for id: ${tusId}`
+      });
+    }
+    if (typeof upload.size === "number" && upload.offset !== upload.size) {
+      throw createError({
+        statusCode: 409,
+        statusMessage: `Staged tus upload is incomplete: ${tusId} (${upload.offset}/${upload.size} bytes)`
+      });
+    }
+    const data = await read(tusId);
+    if (!data) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Staged tus upload data is missing for id: ${tusId}`
+      });
+    }
+    const tusMeta = upload.metadata ?? {};
+    const meta = defu(options.meta ?? {}, {
+      name: tusMeta.filename ?? tusId,
+      mime: tusMeta.filetype ?? "application/octet-stream",
+      type: "",
+      version: 1
+    });
+    const id = await useFileStorage().upload(groupId, data, {
+      meta,
+      transform: options.transform
+    });
+    if (options.removeStaged !== false) {
+      await remove(tusId);
+    }
+    return { id, meta };
+  }
+  return { info, read, remove, promote };
+}

package/dist/runtime/types.d.ts

@@ -52,6 +52,57 @@ export interface ImageTransformResult {
     /** Height of the processed image in px, if sharp could determine it. */
     height?: number;
 }
+/** Reactive state of a single file tracked by `useTusUpload()`. */
+export interface TusUploadState {
+    file: File;
+    /** Upload progress in percent (0-100). */
+    progress: number;
+    /** True once the tus upload finished successfully. */
+    complete: boolean;
+    /** Id of the staged upload on the server (last segment of `uploadUrl`). */
+    tusId?: string;
+    /** Full tus upload URL once the server assigned one. */
+    uploadUrl?: string;
+    /** Message of the last upload error, if any. */
+    error?: string;
+}
+export interface UseTusUploadOptions {
+    /** tus endpoint. Defaults to the route configured via `filer.tus.route`. */
+    endpoint?: string;
+    /**
+     * Extra tus metadata per file, merged over the default
+     * `{ filename, filetype }` pair. Available server-side on the staged
+     * upload and used by `useTusStaging().promote()` as meta fallbacks.
+     */
+    metadata?: (file: File) => Record<string, string>;
+    /** Retry backoff in ms. Default: `[0, 3000, 5000, 10000, 20000]`. */
+    retryDelays?: number[];
+    /** Fixed chunk size in bytes. Default: let tus-js-client decide. */
+    chunkSize?: number;
+    /** Resume matching unfinished uploads from a previous session. Default: `true`. */
+    resume?: boolean;
+    /**
+     * Delete staged uploads via `sendBeacon` when the page is closed while
+     * uploads are still tracked (i.e. not yet promoted and `clear()`ed).
+     * Trades resumability across page loads for a tidy staging area.
+     * Default: `false`.
+     */
+    cleanupOnPageHide?: boolean;
+    onError?: (file: File, error: Error) => void;
+    onSuccess?: (file: File, state: TusUploadState) => void;
+}
+/** Options for `useTusStaging().promote()`. */
+export interface TusPromoteOptions {
+    /**
+     * Overrides for the stored file's meta. Fields not given fall back to the
+     * tus upload metadata (`filename`, `filetype`) and sensible defaults.
+     */
+    meta?: Partial<FileMeta>;
+    /** Optional upload-time image processing, as in `useFileStorage().upload()`. */
+    transform?: ImageTransformOptions;
+    /** Remove the staged upload after promoting it. Default: `true`. */
+    removeStaged?: boolean;
+}
 export interface ExternalRef {
     /** External system identifier, e.g. 'jira', 'sharepoint' */
     source: string;

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type FilerImageOptions, type ModuleOptions } from './module.mjs'
+export { type FilerImageOptions, type FilerTusOptions, type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-filer",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "File storage module for Nuxt",
   "repository": {
     "type": "git",
@@ -36,20 +36,34 @@
     "dist",
     "src/runtime"
   ],
+  "scripts": {
+    "prepack": "nuxt-module-build prepare && 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",
+    "@tus/file-store": "^2.1.0",
+    "@tus/server": "^2.4.1",
     "consola": "^3.4.2",
-    "defu": "^6.1.4"
+    "defu": "^6.1.4",
+    "tus-js-client": "^4.3.1"
   },
   "devDependencies": {
     "@nuxt/devtools": "^3.2.4",
     "@nuxt/eslint-config": "^1.15.2",
     "@nuxt/image": "^2.0.0",
-    "aws4fetch": "^1.0.20",
     "@nuxt/module-builder": "^1.0.2",
     "@nuxt/schema": "^4.4.2",
     "@nuxt/test-utils": "^4.0.0",
     "@types/node": "latest",
+    "aws4fetch": "^1.0.20",
     "changelogen": "^0.6.2",
     "eslint": "^10.1.0",
     "ipx": "^3.1.1",
@@ -79,14 +93,11 @@
       "optional": true
     }
   },
-  "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"
+  "packageManager": "pnpm@10.33.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "sharp"
+    ]
   }
-}
+}

package/src/runtime/composables/tus.ts

@@ -0,0 +1,173 @@
+import { computed, reactive, getCurrentScope, onScopeDispose } from 'vue';
+import { useRuntimeConfig } from 'nuxt/app';
+import { Upload as TusUpload } from 'tus-js-client';
+import type { TusUploadState, UseTusUploadOptions } from '../types';
+
+export type { TusUploadState, UseTusUploadOptions };
+
+const DEFAULT_RETRY_DELAYS = [0, 3000, 5000, 10000, 20000];
+
+/**
+ * Resumable uploads against the module's tus endpoint. Files are staged on
+ * the server; move them into the file storage afterwards with
+ * `useTusStaging().promote()` from one of your own server routes.
+ */
+export function useTusUpload(options: UseTusUploadOptions = {}) {
+  const runtimeConfig = useRuntimeConfig();
+  const endpoint =
+    options.endpoint
+    ?? (runtimeConfig.public.filer as { tusRoute?: string } | undefined)
+      ?.tusRoute
+    ?? '/_filer-tus';
+
+  const items = reactive<Record<string, TusUploadState>>({});
+  // tus Upload instances hold DOM/file handles — keep them out of reactivity.
+  const instances = new Map<string, TusUpload>();
+
+  const uploading = computed(() =>
+    Object.values(items).some((item) => !item.complete && !item.error)
+  );
+  const completed = computed(() =>
+    Object.values(items).filter((item) => item.complete)
+  );
+
+  function captureUploadUrl(state: TusUploadState, upload: TusUpload) {
+    if (upload.url && !state.tusId) {
+      state.uploadUrl = upload.url;
+      state.tusId = upload.url.split('/').pop();
+    }
+  }
+
+  async function start(file: File): Promise<TusUploadState> {
+    const key = file.name;
+    const state: TusUploadState = { file, progress: 0, complete: false };
+    items[key] = state;
+
+    const upload = new TusUpload(file, {
+      endpoint,
+      retryDelays: options.retryDelays ?? DEFAULT_RETRY_DELAYS,
+      chunkSize: options.chunkSize,
+      removeFingerprintOnSuccess: true,
+      metadata: {
+        filename: file.name,
+        filetype: file.type,
+        ...options.metadata?.(file),
+      },
+      onError(error) {
+        const item = items[key];
+        if (!item) return;
+        item.error = error instanceof Error ? error.message : String(error);
+        options.onError?.(file, error as Error);
+      },
+      onProgress(bytesUploaded, bytesTotal) {
+        const item = items[key];
+        if (!item) return;
+        item.progress = bytesTotal ? (bytesUploaded / bytesTotal) * 100 : 0;
+        captureUploadUrl(item, upload);
+      },
+      onSuccess() {
+        const item = items[key];
+        if (!item) return;
+        captureUploadUrl(item, upload);
+        item.progress = 100;
+        item.complete = true;
+        options.onSuccess?.(file, item);
+      },
+    });
+    instances.set(key, upload);
+
+    if (options.resume !== false) {
+      const previous = await upload.findPreviousUploads().catch(() => []);
+      if (previous[0]) upload.resumeFromPreviousUpload(previous[0]);
+    }
+
+    upload.start();
+    return state;
+  }
+
+  /** Start uploads for files not tracked yet (idempotent per file name). */
+  function add(files: File | File[]) {
+    for (const file of Array.isArray(files) ? files : [files]) {
+      if (!items[file.name]) void start(file);
+    }
+  }
+
+  /** Abort a file's upload, delete its staged data, and stop tracking it. */
+  async function remove(file: File | string) {
+    const key = typeof file === 'string' ? file : file.name;
+    const state = items[key];
+    const upload = instances.get(key);
+    instances.delete(key);
+    Reflect.deleteProperty(items, key);
+
+    if (upload) {
+      // terminate = tus DELETE; the staged upload may already be gone.
+      await upload.abort(true).catch(() => {});
+    } else if (state?.uploadUrl) {
+      await fetch(state.uploadUrl, {
+        method: 'DELETE',
+        headers: { 'Tus-Resumable': '1.0.0' },
+      }).catch(() => {});
+    }
+  }
+
+  /** Stop tracking all files without touching staged data (e.g. after promoting). */
+  function clear() {
+    for (const upload of instances.values()) {
+      void upload.abort().catch(() => {});
+    }
+    instances.clear();
+    for (const key of Object.keys(items)) Reflect.deleteProperty(items, key);
+  }
+
+  /** Abort everything and delete all staged uploads. */
+  async function cancel() {
+    await Promise.allSettled(Object.keys(items).map((key) => remove(key)));
+  }
+
+  if (import.meta.client) {
+    // Connection loss beyond retryDelays surfaces as an error; restarting the
+    // same Upload instance continues from the last confirmed offset.
+    const onOnline = () => {
+      for (const [key, upload] of instances) {
+        const item = items[key];
+        if (item && !item.complete) {
+          item.error = undefined;
+          upload.start();
+        }
+      }
+    };
+    const onPageHide = () => {
+      if (!options.cleanupOnPageHide) return;
+      const tusIds = Object.values(items)
+        .map((item) => item.tusId)
+        .filter((id): id is string => !!id);
+      if (tusIds.length === 0) return;
+      navigator.sendBeacon(
+        `${endpoint}/cleanup`,
+        new Blob([JSON.stringify({ tusIds })], { type: 'application/json' })
+      );
+    };
+
+    window.addEventListener('online', onOnline);
+    window.addEventListener('pagehide', onPageHide);
+    if (getCurrentScope()) {
+      onScopeDispose(() => {
+        window.removeEventListener('online', onOnline);
+        window.removeEventListener('pagehide', onPageHide);
+      });
+    }
+  }
+
+  return {
+    endpoint,
+    items,
+    uploading,
+    completed,
+    start,
+    add,
+    remove,
+    clear,
+    cancel,
+  };
+}

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

@@ -0,0 +1,60 @@
+import {
+  defineEventHandler,
+  toWebRequest,
+  readBody,
+  setResponseStatus,
+  createError,
+  type H3Event,
+} from 'h3';
+import type { ServerOptions } from '@tus/server';
+// @ts-expect-error virtual module injected by the module
+import { tusRoute } from '#nuxt-filer-tus';
+import { useTusServer, useTusStaging, isSafeTusId } from '../utils/tus';
+
+type IncomingRequestHook = NonNullable<ServerOptions['onIncomingRequest']>;
+
+/**
+ * `navigator.sendBeacon` cannot speak tus (no custom methods/headers), so a
+ * plain POST sub-route lets a closing page bulk-delete its staged uploads.
+ * The configured `onIncomingRequest` hook guards it like any tus request.
+ */
+async function handleCleanupBeacon(event: H3Event) {
+  const body = await readBody(event).catch(() => null);
+  const tusIds: string[] = Array.isArray(body?.tusIds)
+    ? body.tusIds.filter(isSafeTusId).slice(0, 100)
+    : [];
+
+  const hook = useTusServer().options.onIncomingRequest as
+    | IncomingRequestHook
+    | undefined;
+  if (hook) {
+    const request = toWebRequest(event) as Parameters<IncomingRequestHook>[0];
+    for (const tusId of tusIds) {
+      try {
+        await hook(request, tusId);
+      } catch (error) {
+        const status
+          = (error as { status_code?: number; statusCode?: number })
+            .status_code
+            ?? (error as { statusCode?: number }).statusCode
+            ?? 500;
+        throw createError({ statusCode: status, statusMessage: 'Cleanup rejected' });
+      }
+    }
+  }
+
+  const staging = useTusStaging();
+  await Promise.allSettled(tusIds.map((id) => staging.remove(id)));
+
+  setResponseStatus(event, 204);
+  return null;
+}
+
+export default defineEventHandler(async (event) => {
+  const pathname = event.path.split('?')[0];
+  if (event.method === 'POST' && pathname === `${tusRoute}/cleanup`) {
+    return handleCleanupBeacon(event);
+  }
+
+  return useTusServer().handleWeb(toWebRequest(event));
+});

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

@@ -50,12 +50,12 @@ async function mapWithConcurrency<T, R>(
   limit: number,
   fn: (item: T, index: number) => Promise<R>,
 ): Promise<R[]> {
-  const results = new Array<R>(items.length);
+  const results: R[] = Array.from({ length: items.length });
   let next = 0;
   const worker = async () => {
     while (next < items.length) {
       const index = next++;
-      results[index] = await fn(items[index], index);
+      results[index] = await fn(items[index]!, index);
     }
   };
   const workers = Array.from({ length: Math.min(limit, items.length) || 1 }, worker);
@@ -178,7 +178,7 @@ export function createS3Provider(options: S3ProviderOptions): FileStorageProvide
       for (let i = 0; i < keys.length; i++) {
         const meta = metas[i];
         if (!meta) continue;
-        files.push(toStoredFile(idFromKey(keys[i]), groupId, meta));
+        files.push(toStoredFile(idFromKey(keys[i]!), groupId, meta));
       }
       return files;
     },

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

@@ -0,0 +1,192 @@
+import { createError } from 'h3';
+import { defu } from 'defu';
+import { consola } from 'consola';
+import {
+  Server,
+  type ServerOptions,
+  type DataStore,
+  type Upload,
+} from '@tus/server';
+import { FileStore } from '@tus/file-store';
+// @ts-expect-error virtual module injected by the module
+import { tusRoute, tusStagingDir, tusMaxSize, tusExpiration } from '#nuxt-filer-tus';
+import type { FileMeta, TusPromoteOptions } from '../../../runtime/types';
+import { useFileStorage } from './storage';
+
+export type { TusPromoteOptions };
+
+/**
+ * Everything of `ServerOptions` except `path` (owned by the module config)
+ * can be customized, plus the datastore itself. Note that `useTusStaging()`
+ * requires a datastore with a `read()` method (like the default FileStore).
+ */
+export type TusServerUserOptions = Partial<Omit<ServerOptions, 'path'>> & {
+  datastore?: DataStore;
+};
+
+let userOptions: TusServerUserOptions = {};
+let server: Server | undefined;
+let datastore: DataStore | undefined;
+let expirationTimer: ReturnType<typeof setInterval> | undefined;
+
+/**
+ * Configure the tus server (auth via `onIncomingRequest`, `onUploadFinish`,
+ * a custom datastore, ...). Must be called before the first upload request —
+ * a Nitro plugin is the right place.
+ */
+export function setTusServerOptions(options: TusServerUserOptions) {
+  if (server) {
+    consola.warn(
+      'nuxt-filer: setTusServerOptions() called after the tus server was created — the options are ignored. Call it from a Nitro plugin instead.'
+    );
+    return;
+  }
+  userOptions = options;
+}
+
+function useTusDatastore(): DataStore {
+  if (!datastore) {
+    datastore =
+      userOptions.datastore
+      ?? new FileStore({
+        directory: tusStagingDir,
+        expirationPeriodInMilliseconds:
+          tusExpiration > 0 ? tusExpiration : undefined,
+      });
+  }
+  return datastore;
+}
+
+export function useTusServer(): Server {
+  if (!server) {
+    const { datastore: _datastore, ...serverOptions } = userOptions;
+    server = new Server({
+      path: tusRoute,
+      respectForwardedHeaders: true,
+      maxSize: tusMaxSize > 0 ? tusMaxSize : undefined,
+      datastore: useTusDatastore(),
+      ...serverOptions,
+    });
+
+    if (tusExpiration > 0 && !expirationTimer) {
+      const instance = server;
+      expirationTimer = setInterval(
+        () => instance.cleanUpExpiredUploads().catch(() => {}),
+        Math.min(tusExpiration, 60 * 60 * 1000)
+      );
+      expirationTimer.unref?.();
+    }
+  }
+  return server;
+}
+
+/** Guards datastore ids used in file paths against traversal. */
+export function isSafeTusId(id: unknown): id is string {
+  return (
+    typeof id === 'string'
+    && id.length > 0
+    && id.length <= 255
+    && !id.includes('/')
+    && !id.includes('\\')
+    && !id.includes('..')
+  );
+}
+
+/**
+ * Work with uploads staged by the tus endpoint: inspect, read, remove, or
+ * `promote()` them into the regular file storage.
+ */
+export function useTusStaging() {
+  const store = useTusDatastore();
+
+  async function info(tusId: string): Promise<Upload | null> {
+    if (!isSafeTusId(tusId)) return null;
+    try {
+      return await store.getUpload(tusId);
+    } catch {
+      return null;
+    }
+  }
+
+  async function read(tusId: string): Promise<Buffer | null> {
+    if (!isSafeTusId(tusId)) return null;
+    const readable = store as Partial<Pick<FileStore, 'read'>>;
+    if (typeof readable.read !== 'function') {
+      throw new TypeError(
+        'nuxt-filer: the configured tus datastore does not support read() — useTusStaging() requires a FileStore-compatible datastore'
+      );
+    }
+    try {
+      const chunks: Buffer[] = [];
+      for await (const chunk of readable.read(tusId)) {
+        chunks.push(chunk as Buffer);
+      }
+      return Buffer.concat(chunks);
+    } catch {
+      return null;
+    }
+  }
+
+  async function remove(tusId: string): Promise<boolean> {
+    if (!isSafeTusId(tusId)) return false;
+    try {
+      await store.remove(tusId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Move a completed staged upload into the file storage and (by default)
+   * delete the staged copy. Returns the stored file's id and resolved meta.
+   */
+  async function promote(
+    tusId: string,
+    groupId: string,
+    options: TusPromoteOptions = {}
+  ): Promise<{ id: string; meta: FileMeta }> {
+    const upload = await info(tusId);
+    if (!upload) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `No staged tus upload found for id: ${tusId}`,
+      });
+    }
+    if (typeof upload.size === 'number' && upload.offset !== upload.size) {
+      throw createError({
+        statusCode: 409,
+        statusMessage: `Staged tus upload is incomplete: ${tusId} (${upload.offset}/${upload.size} bytes)`,
+      });
+    }
+
+    const data = await read(tusId);
+    if (!data) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Staged tus upload data is missing for id: ${tusId}`,
+      });
+    }
+
+    const tusMeta = upload.metadata ?? {};
+    const meta = defu(options.meta ?? {}, {
+      name: tusMeta.filename ?? tusId,
+      mime: tusMeta.filetype ?? 'application/octet-stream',
+      type: '',
+      version: 1,
+    }) as FileMeta;
+
+    const id = await useFileStorage().upload(groupId, data, {
+      meta,
+      transform: options.transform,
+    });
+
+    if (options.removeStaged !== false) {
+      await remove(tusId);
+    }
+
+    return { id, meta };
+  }
+
+  return { info, read, remove, promote };
+}

package/src/runtime/types.ts

@@ -56,6 +56,60 @@ export interface ImageTransformResult {
   height?: number;
 }
 
+/** Reactive state of a single file tracked by `useTusUpload()`. */
+export interface TusUploadState {
+  file: File;
+  /** Upload progress in percent (0-100). */
+  progress: number;
+  /** True once the tus upload finished successfully. */
+  complete: boolean;
+  /** Id of the staged upload on the server (last segment of `uploadUrl`). */
+  tusId?: string;
+  /** Full tus upload URL once the server assigned one. */
+  uploadUrl?: string;
+  /** Message of the last upload error, if any. */
+  error?: string;
+}
+
+export interface UseTusUploadOptions {
+  /** tus endpoint. Defaults to the route configured via `filer.tus.route`. */
+  endpoint?: string;
+  /**
+   * Extra tus metadata per file, merged over the default
+   * `{ filename, filetype }` pair. Available server-side on the staged
+   * upload and used by `useTusStaging().promote()` as meta fallbacks.
+   */
+  metadata?: (file: File) => Record<string, string>;
+  /** Retry backoff in ms. Default: `[0, 3000, 5000, 10000, 20000]`. */
+  retryDelays?: number[];
+  /** Fixed chunk size in bytes. Default: let tus-js-client decide. */
+  chunkSize?: number;
+  /** Resume matching unfinished uploads from a previous session. Default: `true`. */
+  resume?: boolean;
+  /**
+   * Delete staged uploads via `sendBeacon` when the page is closed while
+   * uploads are still tracked (i.e. not yet promoted and `clear()`ed).
+   * Trades resumability across page loads for a tidy staging area.
+   * Default: `false`.
+   */
+  cleanupOnPageHide?: boolean;
+  onError?: (file: File, error: Error) => void;
+  onSuccess?: (file: File, state: TusUploadState) => void;
+}
+
+/** Options for `useTusStaging().promote()`. */
+export interface TusPromoteOptions {
+  /**
+   * Overrides for the stored file's meta. Fields not given fall back to the
+   * tus upload metadata (`filename`, `filetype`) and sensible defaults.
+   */
+  meta?: Partial<FileMeta>;
+  /** Optional upload-time image processing, as in `useFileStorage().upload()`. */
+  transform?: ImageTransformOptions;
+  /** Remove the staged upload after promoting it. Default: `true`. */
+  removeStaged?: boolean;
+}
+
 export interface ExternalRef {
   /** External system identifier, e.g. 'jira', 'sharepoint' */
   source: string;