nuxt-filer 0.0.2

package/README.md

@@ -0,0 +1,231 @@
+# nuxt-filer
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+File storage module for Nuxt. Provides a server-side `useFileStorage()` composable with pluggable storage backends — from zero-config local filesystem to custom providers with separate metadata databases and external file sync.
+
+## Features
+
+- **Pluggable provider architecture** — use the built-in unstorage provider or bring your own (Prisma, Drizzle, etc.)
+- **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
+- **Auto-imported** — `useFileStorage()`, types, and provider utilities are auto-imported in server context
+- **Group-based organization** — files are organized by `groupId` (project, ticket, order, etc.)
+
+## Quick Setup
+
+```bash
+npx nuxi module add nuxt-filer
+```
+
+## Configuration
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-filer'],
+  filer: {
+    // Nitro storage mount name (default: 'documents')
+    storageName: 'documents',
+    // Base path for fs-lite driver (default: '.data/documents')
+    storagePath: '.data/documents',
+    // 'unstorage' (built-in) or 'custom' (bring your own provider)
+    provider: 'unstorage',
+  },
+})
+```
+
+## Usage
+
+### Basic — Upload and retrieve files
+
+```ts
+// server/api/files/[groupId].post.ts
+export default defineEventHandler(async (event) => {
+  const groupId = getRouterParam(event, 'groupId')!
+  const body = await readMultipartFormData(event)
+  const file = body![0]!
+
+  const storage = useFileStorage()
+
+  const id = await storage.upload(groupId, file.data, {
+    meta: {
+      name: file.filename || 'unnamed',
+      mime: file.type || 'application/octet-stream',
+      type: 'document',
+      version: 1,
+    },
+  })
+
+  return { id, groupId }
+})
+```
+
+```ts
+// server/api/files/[groupId].get.ts
+export default defineEventHandler(async (event) => {
+  const groupId = getRouterParam(event, 'groupId')!
+  const storage = useFileStorage()
+
+  return await storage.list(groupId)
+})
+```
+
+### `useFileStorage()` API
+
+| Method | Description |
+|---|---|
+| `upload(groupId, data, options?)` | Store a file, returns its ID |
+| `list(groupId)` | List all files in a group |
+| `get(groupId, id)` | Get a file with data and metadata |
+| `getData(groupId, id)` | Get raw binary data only |
+| `getMeta(id)` | Get metadata only |
+| `updateMeta(id, meta)` | Deep-merge metadata update |
+| `remove(groupId, id)` | Delete a file |
+| `clear(groupId)` | Delete all files in a group |
+| `has(groupId, id)` | Check if a file exists |
+| `findByMeta(key, value, groupId?)` | Find a file by metadata field |
+| `checkDuplicate(groupId, key, value)` | Check if a duplicate exists |
+| `getLatestVersions(groupId)` | Get latest version of each file by name |
+| `getNextVersionNumber(files, name)` | Calculate next version number |
+| `external?.sync(groupId, id)` | Sync with external system (if provider supports it) |
+| `external?.push(groupId, id, data, meta)` | Push to external system |
+| `external?.pull(groupId, ref)` | Pull from external system |
+
+## Custom Provider
+
+For advanced use cases (database-backed metadata, S3 storage, external file sync), implement the `FileStorageProvider` interface and register it in a Nitro plugin:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-filer'],
+  filer: {
+    provider: 'custom',
+  },
+})
+```
+
+```ts
+// server/plugins/file-provider.ts
+export default defineNitroPlugin(() => {
+  setFileStorageProvider({
+    async create(groupId, data, meta) {
+      // Store binary data (e.g. S3, unstorage)
+      // Store metadata (e.g. Prisma, Drizzle)
+      return { id: '...' }
+    },
+    async get(groupId, id) { /* ... */ },
+    async getData(groupId, id) { /* ... */ },
+    async getMeta(id) { /* ... */ },
+    async list(groupId) { /* ... */ },
+    async update(id, meta) { /* ... */ },
+    async remove(groupId, id) { /* ... */ },
+    async clear(groupId) { /* ... */ },
+    async has(groupId, id) { /* ... */ },
+    async findByMeta(filter) { /* ... */ },
+
+    // Optional: external file sync
+    external: {
+      async sync(groupId, id) { /* ... */ },
+      async push(groupId, id, data, meta) { /* ... */ },
+      async pull(groupId, externalRef) { /* ... */ },
+    },
+  })
+})
+```
+
+### Provider interface
+
+```ts
+interface FileStorageProvider {
+  create(groupId: string, data: Buffer | Uint8Array, meta?: FileMeta): Promise<{ id: string }>
+  get(groupId: string, id: string): Promise<StoredFile | null>
+  getData(groupId: string, id: string): Promise<Buffer | null>
+  getMeta(id: string): Promise<FileMeta | null>
+  list(groupId: string): Promise<StoredFile[]>
+  update(id: string, meta: Partial<FileMeta>): Promise<void>
+  remove(groupId: string, id: string): Promise<void>
+  clear(groupId: string): Promise<void>
+  has(groupId: string, id: string): Promise<boolean>
+  findByMeta(filter: { key: string; value: unknown; groupId?: string }): Promise<StoredFile | null>
+  external?: FileStorageExternalProvider
+}
+```
+
+### Types
+
+```ts
+interface FileMeta {
+  name: string
+  mime: string
+  type: string
+  version: number
+  username?: string
+  comment?: string
+  [key: string]: unknown  // extend with your own fields
+}
+
+interface StoredFile {
+  id: string
+  groupId: string
+  data?: Buffer
+  meta: FileMeta
+  external?: ExternalRef
+  createdAt?: Date
+  updatedAt?: Date
+}
+
+interface ExternalRef {
+  source: string       // e.g. 'jira', 'sharepoint'
+  externalId: string
+  externalUrl?: string
+  cachedAt?: Date
+}
+```
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+
+  ```bash
+  # Install dependencies
+  pnpm install
+
+  # Generate type stubs
+  pnpm run dev:prepare
+
+  # Develop with the playground
+  pnpm run dev
+
+  # Run ESLint
+  pnpm run lint
+
+  # Run Vitest
+  pnpm run test
+
+  # Release new version
+  pnpm run release
+  ```
+
+</details>
+
+## License
+
+[MIT](./LICENSE)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-filer/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-filer
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-filer.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-filer
+[license-src]: https://img.shields.io/npm/l/nuxt-filer.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-filer
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,14 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Nitro storage mount name for binary file data. Default: 'documents' */
+    storageName?: string;
+    /** Base path for the default fs-lite storage driver. Default: '.data/documents' */
+    storagePath?: string;
+    /** Provider mode. 'unstorage' uses the built-in unstorage provider. 'custom' expects you to call setFileStorageProvider() in a Nitro plugin. Default: 'unstorage' */
+    provider?: 'unstorage' | 'custom';
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-filer",
+  "configKey": "filer",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,64 @@
+import { defineNuxtModule, createResolver, addServerImports, addImports } from '@nuxt/kit';
+import { consola } from 'consola';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-filer",
+    configKey: "filer"
+  },
+  defaults: {
+    storageName: "documents",
+    storagePath: ".data/documents",
+    provider: "unstorage"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    addServerImports([
+      {
+        name: "useFileStorage",
+        from: resolver.resolve("./runtime/server/utils/storage")
+      }
+    ]);
+    const providerSpecifier = resolver.resolve("./runtime/server/provider");
+    addServerImports([
+      { name: "setFileStorageProvider", from: providerSpecifier },
+      { name: "useFileStorageProvider", from: providerSpecifier }
+    ]);
+    addServerImports([
+      {
+        name: "createUnstorageProvider",
+        from: resolver.resolve("./runtime/server/providers/unstorage")
+      }
+    ]);
+    const typesSpecifier = "nuxt-filer/runtime/types";
+    addImports([
+      { name: "FileMeta", from: typesSpecifier, type: true },
+      { name: "StoredFile", from: typesSpecifier, type: true },
+      { name: "ExternalRef", from: typesSpecifier, type: true },
+      { name: "FileStorageProvider", from: typesSpecifier, type: true },
+      {
+        name: "FileStorageExternalProvider",
+        from: typesSpecifier,
+        type: true
+      }
+    ]);
+    nuxt.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.virtual = nitroConfig.virtual || {};
+      nitroConfig.virtual["#nuxt-filer-options"] = `export const storageName = ${JSON.stringify(options.storageName)}`;
+      if (options.provider === "unstorage") {
+        nitroConfig.storage = nitroConfig.storage || {};
+        nitroConfig.storage[options.storageName] = {
+          driver: "fsLite",
+          base: options.storagePath
+        };
+        nitroConfig.plugins = nitroConfig.plugins || [];
+        nitroConfig.plugins.push(
+          resolver.resolve("./runtime/server/plugins/default-provider")
+        );
+      }
+    });
+    consola.success("nuxt-filer ready");
+  }
+});
+
+export { module as default };

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

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

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

@@ -0,0 +1,6 @@
+import { storageName } from "#nuxt-filer-options";
+import { createUnstorageProvider } from "../providers/unstorage.js";
+import { setFileStorageProvider } from "../provider.js";
+export default defineNitroPlugin(() => {
+  setFileStorageProvider(createUnstorageProvider(storageName));
+});

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

@@ -0,0 +1,3 @@
+import type { FileStorageProvider } from '../../runtime/types.js';
+export declare function setFileStorageProvider(provider: FileStorageProvider): void;
+export declare function useFileStorageProvider(): FileStorageProvider;

package/dist/runtime/server/provider.js

@@ -0,0 +1,12 @@
+let _provider = null;
+export function setFileStorageProvider(provider) {
+  _provider = provider;
+}
+export function useFileStorageProvider() {
+  if (!_provider) {
+    throw new Error(
+      'No file storage provider configured. Call setFileStorageProvider() in a Nitro plugin or set provider option to "unstorage" in module config.'
+    );
+  }
+  return _provider;
+}

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

@@ -0,0 +1,7 @@
+import type { FileStorageProvider } from '../../../runtime/types.js';
+/**
+ * Built-in provider that uses Nitro's useStorage() for both binary data and metadata.
+ * Metadata is stored as JSON sidecar files alongside the binary data.
+ * No database dependency required.
+ */
+export declare function createUnstorageProvider(storageName: string): FileStorageProvider;

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

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+export function createUnstorageProvider(storageName) {
+  function getStorage() {
+    return useStorage(storageName);
+  }
+  function dataKey(groupId, id) {
+    return `${groupId}:data:${id}`;
+  }
+  function metaKey(groupId, id) {
+    return `${groupId}:meta:${id}`;
+  }
+  return {
+    async create(groupId, data, meta) {
+      const storage = getStorage();
+      const id = randomUUID();
+      await storage.setItemRaw(dataKey(groupId, id), data);
+      if (meta) {
+        await storage.setItem(metaKey(groupId, id), {
+          ...meta,
+          _createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          _updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      return { id };
+    },
+    async get(groupId, id) {
+      const storage = getStorage();
+      const data = await storage.getItemRaw(dataKey(groupId, id));
+      const metaData = await storage.getItem(metaKey(groupId, id));
+      if (!data && !metaData) return null;
+      return {
+        id,
+        groupId,
+        data: data ?? void 0,
+        meta: stripInternal(metaData),
+        createdAt: metaData?._createdAt ? new Date(metaData._createdAt) : void 0,
+        updatedAt: metaData?._updatedAt ? new Date(metaData._updatedAt) : void 0
+      };
+    },
+    async getData(groupId, id) {
+      return await getStorage().getItemRaw(dataKey(groupId, id));
+    },
+    async getMeta(id) {
+      const storage = getStorage();
+      const keys = await storage.getKeys();
+      const key = keys.find((k) => k.endsWith(`:meta:${id}`));
+      if (!key) return null;
+      const metaData = await storage.getItem(key);
+      return metaData ? stripInternal(metaData) : null;
+    },
+    async list(groupId) {
+      const storage = getStorage();
+      const keys = await storage.getKeys(groupId);
+      const metaKeys = keys.filter((k) => k.includes(":meta:"));
+      const files = [];
+      for (const key of metaKeys) {
+        const parts = key.split(":");
+        const id = parts[parts.length - 1];
+        const metaData = await storage.getItem(key);
+        if (!metaData) continue;
+        files.push({
+          id,
+          groupId,
+          meta: stripInternal(metaData),
+          createdAt: metaData._createdAt ? new Date(metaData._createdAt) : void 0,
+          updatedAt: metaData._updatedAt ? new Date(metaData._updatedAt) : void 0
+        });
+      }
+      return files;
+    },
+    async update(id, meta) {
+      const storage = getStorage();
+      const keys = await storage.getKeys();
+      const key = keys.find((k) => k.endsWith(`:meta:${id}`));
+      if (!key) throw new Error(`File metadata not found: ${id}`);
+      const existing = await storage.getItem(key);
+      await storage.setItem(key, {
+        ...existing,
+        ...meta,
+        _updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    },
+    async remove(groupId, id) {
+      const storage = getStorage();
+      await storage.removeItem(dataKey(groupId, id));
+      await storage.removeItem(metaKey(groupId, id));
+    },
+    async clear(groupId) {
+      const storage = getStorage();
+      const keys = await storage.getKeys(groupId);
+      for (const key of keys) {
+        await storage.removeItem(key);
+      }
+    },
+    async has(groupId, id) {
+      return await getStorage().hasItem(dataKey(groupId, id));
+    },
+    async findByMeta(filter) {
+      const storage = getStorage();
+      const prefix = filter.groupId ?? "";
+      const keys = await storage.getKeys(prefix);
+      const metaKeys = keys.filter((k) => k.includes(":meta:"));
+      for (const key of metaKeys) {
+        const metaData = await storage.getItem(key);
+        if (!metaData) continue;
+        if (metaData[filter.key] === filter.value) {
+          const parts = key.split(":");
+          const id = parts[parts.length - 1];
+          const metaIdx = parts.indexOf("meta");
+          const groupId = parts.slice(0, metaIdx).join(":");
+          return {
+            id,
+            groupId,
+            meta: stripInternal(metaData),
+            createdAt: metaData._createdAt ? new Date(metaData._createdAt) : void 0,
+            updatedAt: metaData._updatedAt ? new Date(metaData._updatedAt) : void 0
+          };
+        }
+      }
+      return null;
+    }
+  };
+}
+function stripInternal(meta) {
+  if (!meta) return { name: "", mime: "", type: "", version: 0 };
+  const { _createdAt, _updatedAt, ...rest } = meta;
+  return rest;
+}

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

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

@@ -0,0 +1,24 @@
+import type { FileMeta, StoredFile, ExternalRef, FileStorageProvider } from '../../../runtime/types.js';
+export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider };
+export declare const useFileStorage: () => {
+    upload: (groupId: string, data: Buffer | Uint8Array, options?: {
+        meta?: FileMeta;
+    }) => Promise<string>;
+    list: (groupId: string) => Promise<StoredFile[]>;
+    get: (groupId: string, id: string) => Promise<StoredFile | null>;
+    getData: (groupId: string, id: string) => Promise<Buffer | null>;
+    getMeta: (id: string) => Promise<FileMeta | null>;
+    updateMeta: (id: string, meta: Partial<FileMeta>) => Promise<void>;
+    remove: (groupId: string, id: string) => Promise<void>;
+    clear: (groupId: string) => Promise<void>;
+    has: (groupId: string, id: string) => Promise<boolean>;
+    findByMeta: (key: string, value: unknown, groupId?: string) => Promise<StoredFile | null>;
+    checkDuplicate: (groupId: string, key: string, value: unknown) => Promise<boolean>;
+    getLatestVersions: (groupId: string) => Promise<StoredFile[]>;
+    getNextVersionNumber: (files: StoredFile[], name: string) => number;
+    external: {
+        sync: (groupId: string, id: string) => Promise<void>;
+        push: (groupId: string, id: string, data: Buffer, meta: FileMeta) => Promise<void>;
+        pull: (groupId: string, externalRef: ExternalRef) => Promise<StoredFile>;
+    } | undefined;
+};

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

@@ -0,0 +1,82 @@
+import { defu } from "defu";
+import { useFileStorageProvider } from "../provider.js";
+export const useFileStorage = () => {
+  const provider = useFileStorageProvider();
+  async function upload(groupId, data, options = {}) {
+    const { id } = await provider.create(groupId, data, options.meta);
+    return id;
+  }
+  async function list(groupId) {
+    return await provider.list(groupId);
+  }
+  async function get(groupId, id) {
+    return await provider.get(groupId, id);
+  }
+  async function getData(groupId, id) {
+    return await provider.getData(groupId, id);
+  }
+  async function getMeta(id) {
+    return await provider.getMeta(id);
+  }
+  async function updateMeta(id, meta) {
+    const existing = await provider.getMeta(id);
+    const merged = defu(meta, existing);
+    await provider.update(id, merged);
+  }
+  async function remove(groupId, id) {
+    await provider.remove(groupId, id);
+  }
+  async function clear(groupId) {
+    await provider.clear(groupId);
+  }
+  async function has(groupId, id) {
+    return await provider.has(groupId, id);
+  }
+  async function findByMeta(key, value, groupId) {
+    return await provider.findByMeta({ key, value, groupId });
+  }
+  async function checkDuplicate(groupId, key, value) {
+    const file = await provider.findByMeta({ key, value, groupId });
+    return !!file;
+  }
+  async function getLatestVersions(groupId) {
+    const files = await list(groupId);
+    const fileMap = /* @__PURE__ */ new Map();
+    for (const file of files) {
+      const existing = fileMap.get(file.meta.name);
+      const version = file.meta.version ?? 0;
+      const existingVersion = existing?.meta.version ?? 0;
+      if (!existing || version > existingVersion) {
+        fileMap.set(file.meta.name, file);
+      }
+    }
+    return Array.from(fileMap.values());
+  }
+  function getNextVersionNumber(files, name) {
+    const matching = files.filter((f) => f.meta.name === name).sort((a, b) => a.meta.version - b.meta.version);
+    const newest = matching[matching.length - 1];
+    if (!newest) return 1;
+    return newest.meta.version + 1;
+  }
+  const external = provider.external ? {
+    sync: provider.external.sync.bind(provider.external),
+    push: provider.external.push.bind(provider.external),
+    pull: provider.external.pull.bind(provider.external)
+  } : void 0;
+  return {
+    upload,
+    list,
+    get,
+    getData,
+    getMeta,
+    updateMeta,
+    remove,
+    clear,
+    has,
+    findByMeta,
+    checkDuplicate,
+    getLatestVersions,
+    getNextVersionNumber,
+    external
+  };
+};

package/dist/runtime/types.d.ts

@@ -0,0 +1,56 @@
+export interface FileMeta {
+    name: string;
+    mime: string;
+    type: string;
+    version: number;
+    username?: string;
+    comment?: string;
+    [key: string]: unknown;
+}
+export interface ExternalRef {
+    /** External system identifier, e.g. 'jira', 'sharepoint' */
+    source: string;
+    /** ID of the file in the external system */
+    externalId: string;
+    /** URL to the file in the external system */
+    externalUrl?: string;
+    /** When metadata/thumbnail was last synced */
+    cachedAt?: Date;
+}
+export interface StoredFile {
+    id: string;
+    groupId: string;
+    data?: Buffer;
+    meta: FileMeta;
+    external?: ExternalRef;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface FileStorageExternalProvider {
+    /** Sync local cache with the external system (pull latest metadata/thumbnail) */
+    sync(groupId: string, id: string): Promise<void>;
+    /** Push local file data and metadata to the external system */
+    push(groupId: string, id: string, data: Buffer, meta: FileMeta): Promise<void>;
+    /** Pull a file from the external system into local storage */
+    pull(groupId: string, externalRef: ExternalRef): Promise<StoredFile>;
+}
+export interface FileStorageProvider {
+    create(groupId: string, data: Buffer | Uint8Array, meta?: FileMeta): Promise<{
+        id: string;
+    }>;
+    get(groupId: string, id: string): Promise<StoredFile | null>;
+    getData(groupId: string, id: string): Promise<Buffer | null>;
+    getMeta(id: string): Promise<FileMeta | null>;
+    list(groupId: string): Promise<StoredFile[]>;
+    update(id: string, meta: Partial<FileMeta>): Promise<void>;
+    remove(groupId: string, id: string): Promise<void>;
+    clear(groupId: string): Promise<void>;
+    has(groupId: string, id: string): Promise<boolean>;
+    findByMeta(filter: {
+        key: string;
+        value: unknown;
+        groupId?: string;
+    }): Promise<StoredFile | null>;
+    /** Optional external file sync support */
+    external?: FileStorageExternalProvider;
+}

package/dist/types.d.mts

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "nuxt-filer",
+  "version": "0.0.2",
+  "description": "File storage module for Nuxt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Niki2k1/nuxt-filer.git"
+  },
+  "homepage": "https://github.com/Niki2k1/nuxt-filer#readme",
+  "bugs": {
+    "url": "https://github.com/Niki2k1/nuxt-filer/issues"
+  },
+  "license": "MIT",
+  "author": "Niki2k1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./runtime/types": {
+      "types": "./src/runtime/types.ts",
+      "import": "./src/runtime/types.ts",
+      "default": "./src/runtime/types.ts"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "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",
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.2.4",
+    "@nuxt/eslint-config": "^1.15.2",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.4.2",
+    "@nuxt/test-utils": "^4.0.0",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.1.0",
+    "nuxt": "^4.4.2",
+    "typescript": "~6.0.2",
+    "vitest": "^4.1.2",
+    "vue-tsc": "^3.2.6"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}

package/src/runtime/server/plugins/default-provider.ts

@@ -0,0 +1,8 @@
+// @ts-expect-error virtual module
+import { storageName } from '#nuxt-filer-options';
+import { createUnstorageProvider } from '../providers/unstorage';
+import { setFileStorageProvider } from '../provider';
+
+export default defineNitroPlugin(() => {
+  setFileStorageProvider(createUnstorageProvider(storageName));
+});

package/src/runtime/server/provider.ts

@@ -0,0 +1,16 @@
+import type { FileStorageProvider } from '../../runtime/types';
+
+let _provider: FileStorageProvider | null = null;
+
+export function setFileStorageProvider(provider: FileStorageProvider) {
+  _provider = provider;
+}
+
+export function useFileStorageProvider(): FileStorageProvider {
+  if (!_provider) {
+    throw new Error(
+      'No file storage provider configured. Call setFileStorageProvider() in a Nitro plugin or set provider option to "unstorage" in module config.'
+    );
+  }
+  return _provider;
+}

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

@@ -0,0 +1,194 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  FileStorageProvider,
+  FileMeta,
+  StoredFile,
+} from '../../../runtime/types';
+
+/**
+ * Built-in provider that uses Nitro's useStorage() for both binary data and metadata.
+ * Metadata is stored as JSON sidecar files alongside the binary data.
+ * No database dependency required.
+ */
+export function createUnstorageProvider(
+  storageName: string
+): FileStorageProvider {
+  function getStorage() {
+    return useStorage(storageName);
+  }
+
+  function dataKey(groupId: string, id: string) {
+    return `${groupId}:data:${id}`;
+  }
+
+  function metaKey(groupId: string, id: string) {
+    return `${groupId}:meta:${id}`;
+  }
+
+  return {
+    async create(groupId, data, meta) {
+      const storage = getStorage();
+      const id = randomUUID();
+
+      await storage.setItemRaw(dataKey(groupId, id), data);
+
+      if (meta) {
+        await storage.setItem(metaKey(groupId, id), {
+          ...meta,
+          _createdAt: new Date().toISOString(),
+          _updatedAt: new Date().toISOString(),
+        });
+      }
+
+      return { id };
+    },
+
+    async get(groupId, id) {
+      const storage = getStorage();
+      const data = await storage.getItemRaw<Buffer>(dataKey(groupId, id));
+      const metaData = await storage.getItem<
+        FileMeta & { _createdAt?: string; _updatedAt?: string }
+      >(metaKey(groupId, id));
+
+      if (!data && !metaData) return null;
+
+      return {
+        id,
+        groupId,
+        data: data ?? undefined,
+        meta: stripInternal(metaData),
+        createdAt: metaData?._createdAt
+          ? new Date(metaData._createdAt)
+          : undefined,
+        updatedAt: metaData?._updatedAt
+          ? new Date(metaData._updatedAt)
+          : undefined,
+      };
+    },
+
+    async getData(groupId, id) {
+      return await getStorage().getItemRaw<Buffer>(dataKey(groupId, id));
+    },
+
+    async getMeta(id) {
+      const storage = getStorage();
+      const keys = await storage.getKeys();
+      const key = keys.find((k) => k.endsWith(`:meta:${id}`));
+      if (!key) return null;
+
+      const metaData = await storage.getItem<FileMeta>(key);
+      return metaData ? stripInternal(metaData) : null;
+    },
+
+    async list(groupId) {
+      const storage = getStorage();
+      const keys = await storage.getKeys(groupId);
+
+      // Get unique file IDs by filtering meta keys (format: groupId:meta:id)
+      const metaKeys = keys.filter((k) => k.includes(':meta:'));
+      const files: StoredFile[] = [];
+
+      for (const key of metaKeys) {
+        const parts = key.split(':');
+        const id = parts[parts.length - 1]!;
+
+        const metaData = await storage.getItem<
+          FileMeta & { _createdAt?: string; _updatedAt?: string }
+        >(key);
+        if (!metaData) continue;
+
+        files.push({
+          id,
+          groupId,
+          meta: stripInternal(metaData),
+          createdAt: metaData._createdAt
+            ? new Date(metaData._createdAt)
+            : undefined,
+          updatedAt: metaData._updatedAt
+            ? new Date(metaData._updatedAt)
+            : undefined,
+        });
+      }
+
+      return files;
+    },
+
+    async update(id, meta) {
+      const storage = getStorage();
+      const keys = await storage.getKeys();
+      const key = keys.find((k) => k.endsWith(`:meta:${id}`));
+      if (!key) throw new Error(`File metadata not found: ${id}`);
+
+      const existing = await storage.getItem<
+        FileMeta & { _createdAt?: string; _updatedAt?: string }
+      >(key);
+
+      await storage.setItem(key, {
+        ...existing,
+        ...meta,
+        _updatedAt: new Date().toISOString(),
+      });
+    },
+
+    async remove(groupId, id) {
+      const storage = getStorage();
+      await storage.removeItem(dataKey(groupId, id));
+      await storage.removeItem(metaKey(groupId, id));
+    },
+
+    async clear(groupId) {
+      const storage = getStorage();
+      const keys = await storage.getKeys(groupId);
+      for (const key of keys) {
+        await storage.removeItem(key);
+      }
+    },
+
+    async has(groupId, id) {
+      return await getStorage().hasItem(dataKey(groupId, id));
+    },
+
+    async findByMeta(filter) {
+      const storage = getStorage();
+      const prefix = filter.groupId ?? '';
+      const keys = await storage.getKeys(prefix);
+      const metaKeys = keys.filter((k) => k.includes(':meta:'));
+
+      for (const key of metaKeys) {
+        const metaData = await storage.getItem<
+          FileMeta & { _createdAt?: string; _updatedAt?: string }
+        >(key);
+        if (!metaData) continue;
+
+        if (metaData[filter.key] === filter.value) {
+          const parts = key.split(':');
+          const id = parts[parts.length - 1]!;
+          const metaIdx = parts.indexOf('meta');
+          const groupId = parts.slice(0, metaIdx).join(':');
+
+          return {
+            id,
+            groupId,
+            meta: stripInternal(metaData),
+            createdAt: metaData._createdAt
+              ? new Date(metaData._createdAt)
+              : undefined,
+            updatedAt: metaData._updatedAt
+              ? new Date(metaData._updatedAt)
+              : undefined,
+          };
+        }
+      }
+
+      return null;
+    },
+  };
+}
+
+function stripInternal(
+  meta: (FileMeta & { _createdAt?: string; _updatedAt?: string }) | null
+): FileMeta {
+  if (!meta) return { name: '', mime: '', type: '', version: 0 };
+  const { _createdAt, _updatedAt, ...rest } = meta;
+  return rest as FileMeta;
+}

package/src/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

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

@@ -0,0 +1,140 @@
+import { defu } from 'defu';
+import type {
+  FileMeta,
+  StoredFile,
+  ExternalRef,
+  FileStorageProvider,
+} from '../../../runtime/types';
+import { useFileStorageProvider } from '../provider';
+
+export type { FileMeta, StoredFile, ExternalRef, FileStorageProvider };
+
+export const useFileStorage = () => {
+  const provider = useFileStorageProvider();
+
+  async function upload(
+    groupId: string,
+    data: Buffer | Uint8Array,
+    options: { meta?: FileMeta } = {}
+  ): Promise<string> {
+    const { id } = await provider.create(groupId, data, options.meta);
+    return id;
+  }
+
+  async function list(groupId: string): Promise<StoredFile[]> {
+    return await provider.list(groupId);
+  }
+
+  async function get(
+    groupId: string,
+    id: string
+  ): Promise<StoredFile | null> {
+    return await provider.get(groupId, id);
+  }
+
+  async function getData(
+    groupId: string,
+    id: string
+  ): Promise<Buffer | null> {
+    return await provider.getData(groupId, id);
+  }
+
+  async function getMeta(id: string): Promise<FileMeta | null> {
+    return await provider.getMeta(id);
+  }
+
+  async function updateMeta(id: string, meta: Partial<FileMeta>) {
+    const existing = await provider.getMeta(id);
+    const merged = defu(meta, existing) as Partial<FileMeta>;
+    await provider.update(id, merged);
+  }
+
+  async function remove(groupId: string, id: string) {
+    await provider.remove(groupId, id);
+  }
+
+  async function clear(groupId: string) {
+    await provider.clear(groupId);
+  }
+
+  async function has(groupId: string, id: string): Promise<boolean> {
+    return await provider.has(groupId, id);
+  }
+
+  async function findByMeta(
+    key: string,
+    value: unknown,
+    groupId?: string
+  ): Promise<StoredFile | null> {
+    return await provider.findByMeta({ key, value, groupId });
+  }
+
+  async function checkDuplicate(
+    groupId: string,
+    key: string,
+    value: unknown
+  ): Promise<boolean> {
+    const file = await provider.findByMeta({ key, value, groupId });
+    return !!file;
+  }
+
+  /**
+   * Get the latest version of each file (by name) within a group.
+   */
+  async function getLatestVersions(groupId: string): Promise<StoredFile[]> {
+    const files = await list(groupId);
+    const fileMap = new Map<string, StoredFile>();
+
+    for (const file of files) {
+      const existing = fileMap.get(file.meta.name);
+      const version = file.meta.version ?? 0;
+      const existingVersion = existing?.meta.version ?? 0;
+
+      if (!existing || version > existingVersion) {
+        fileMap.set(file.meta.name, file);
+      }
+    }
+
+    return Array.from(fileMap.values());
+  }
+
+  /**
+   * Determine the next version number for a file name.
+   */
+  function getNextVersionNumber(files: StoredFile[], name: string): number {
+    const matching = files
+      .filter((f) => f.meta.name === name)
+      .sort((a, b) => a.meta.version - b.meta.version);
+
+    const newest = matching[matching.length - 1];
+    if (!newest) return 1;
+
+    return newest.meta.version + 1;
+  }
+
+  // External file operations (only available if provider supports it)
+  const external = provider.external
+    ? {
+        sync: provider.external.sync.bind(provider.external),
+        push: provider.external.push.bind(provider.external),
+        pull: provider.external.pull.bind(provider.external),
+      }
+    : undefined;
+
+  return {
+    upload,
+    list,
+    get,
+    getData,
+    getMeta,
+    updateMeta,
+    remove,
+    clear,
+    has,
+    findByMeta,
+    checkDuplicate,
+    getLatestVersions,
+    getNextVersionNumber,
+    external,
+  };
+};

package/src/runtime/types.ts

@@ -0,0 +1,68 @@
+export interface FileMeta {
+  name: string;
+  mime: string;
+  type: string;
+  version: number;
+  username?: string;
+  comment?: string;
+  [key: string]: unknown;
+}
+
+export interface ExternalRef {
+  /** External system identifier, e.g. 'jira', 'sharepoint' */
+  source: string;
+  /** ID of the file in the external system */
+  externalId: string;
+  /** URL to the file in the external system */
+  externalUrl?: string;
+  /** When metadata/thumbnail was last synced */
+  cachedAt?: Date;
+}
+
+export interface StoredFile {
+  id: string;
+  groupId: string;
+  data?: Buffer;
+  meta: FileMeta;
+  external?: ExternalRef;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface FileStorageExternalProvider {
+  /** Sync local cache with the external system (pull latest metadata/thumbnail) */
+  sync(groupId: string, id: string): Promise<void>;
+  /** Push local file data and metadata to the external system */
+  push(
+    groupId: string,
+    id: string,
+    data: Buffer,
+    meta: FileMeta
+  ): Promise<void>;
+  /** Pull a file from the external system into local storage */
+  pull(groupId: string, externalRef: ExternalRef): Promise<StoredFile>;
+}
+
+export interface FileStorageProvider {
+  create(
+    groupId: string,
+    data: Buffer | Uint8Array,
+    meta?: FileMeta
+  ): Promise<{ id: string }>;
+  get(groupId: string, id: string): Promise<StoredFile | null>;
+  getData(groupId: string, id: string): Promise<Buffer | null>;
+  getMeta(id: string): Promise<FileMeta | null>;
+  list(groupId: string): Promise<StoredFile[]>;
+  update(id: string, meta: Partial<FileMeta>): Promise<void>;
+  remove(groupId: string, id: string): Promise<void>;
+  clear(groupId: string): Promise<void>;
+  has(groupId: string, id: string): Promise<boolean>;
+  findByMeta(filter: {
+    key: string;
+    value: unknown;
+    groupId?: string;
+  }): Promise<StoredFile | null>;
+
+  /** Optional external file sync support */
+  external?: FileStorageExternalProvider;
+}