nuxt-file-storage 0.3.1 → 0.3.3-beta.0

package/README.md

@@ -2,10 +2,11 @@
 
 # Nuxt File Storage
 
-[![Visits Badge](https://badges.pufler.dev/visits/nyllre/nuxt-file-storage)](https://badges.pufler.dev)
+<!-- [![Visits Badge](https://badges.pufler.dev/visits/nyllre/nuxt-file-storage)](https://badges.pufler.dev) -->
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![License][license-src]][license-href]
+[![nuxt.care health](https://img.shields.io/endpoint?url=https://nuxt.care/api/badge/nuxt-file-storage&style=flat&colorA=18181B&colorB=28CF8D)](https://nuxt.care/?search=nuxt-file-storage)
 [![Nuxt][nuxt-src]][nuxt-href]
 
 Easy solution to store files in your nuxt apps. Be able to upload files from the frontend and receive them from the backend to then save the files in your project.
@@ -83,6 +84,8 @@ You can use Nuxt Storage to get the files from the `<input>` tag:
 ```
 The `files` return a ref object that contains the files
 
+The `clearFiles` function empties the files list without needing to reassign `files.value = []`
+
 > `handleFileInput` returns a promise in case you need to check if the file input has concluded
 
 <br>
@@ -130,10 +133,57 @@ You have to create a new instance of `useFileStorage` for each input field
 ```
 by calling a new `useFileStorage` instance you separate the internal logic between the inputs
 
+<br>
+
+#### Using with `defineExpose`
+
+The `files` ref is iterable, so it works naturally with `defineExpose` in child components:
+
+```html
+<!-- Child Component -->
+<template>
+	<input type="file" @input="handleFileInput" multiple />
+</template>
+
+<script setup>
+const { handleFileInput, files, clearFiles } = useFileStorage()
+
+defineExpose({
+	files,
+	handleFileInput,
+	clearFiles,
+})
+</script>
+```
+
+```html
+<!-- Parent Component -->
+<template>
+	<ChildComponent ref="childRef" />
+	<button @click="iterateFiles">Show Files</button>
+</template>
+
+<script setup>
+const childRef = ref()
+
+const iterateFiles = () => {
+	// Direct iteration — no double .value needed
+	for (const file of childRef.value.files) {
+		console.log(file.name)
+	}
+
+	// Traditional .value access still works
+	console.log(childRef.value.files.value)
+}
+</script>
+```
+
+<br>
+
 ### Handling files in the backend
 using Nitro Server Engine, we will make an api route that receives the files and stores them in the folder `userFiles`
 ```ts
-import { ServerFile } from "nuxt-file-storage";
+import { ServerFile } from "#file-storage/types";
 
 export default defineEventHandler(async (event) => {
 	const { files } = await readBody<{ files: ServerFile[] }>(event)
@@ -187,11 +237,11 @@ npm run dev
 
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/nuxt-file-storage/latest.svg?style=flat&colorA=18181B&colorB=28CF8D
-[npm-version-href]: https://npmjs.com/package/nuxt-file-storage
-[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-file-storage.svg?style=flat&colorA=18181B&colorB=28CF8D
-[npm-downloads-href]: https://npmjs.com/package/nuxt-file-storage
-[license-src]: https://img.shields.io/npm/l/nuxt-file-storage.svg?style=flat&colorA=18181B&colorB=28CF8D
-[license-href]: https://npmjs.com/package/nuxt-file-storage
+[npm-version-src]: https://npmx.dev/api/registry/badge/version/nuxt-file-storage
+[npm-version-href]: https://npmx.dev/package/nuxt-file-storage
+[npm-downloads-src]: https://npmx.dev/api/registry/badge/downloads-year/nuxt-file-storage
+[npm-downloads-href]: https://npmx.dev/package/nuxt-file-storage
+[license-src]: https://npmx.dev/api/registry/badge/license/nuxt-file-storage
+[license-href]: https://npmx.dev/package/nuxt-file-storage
 [nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
 [nuxt-href]: https://nuxt.com/modules/nuxt-file-storage

package/dist/module.d.mts

@@ -1,32 +1,7 @@
 import * as _nuxt_schema from '@nuxt/schema';
-
-interface ServerFile {
-	name: string
-	content: string
-	size: string
-	type: string
-	lastModified: string
-}
-
-interface ClientFile extends Blob {
-	content: string | ArrayBuffer | null | undefined
-	name: string
-	lastModified: number
-}
-
-interface ModuleOptions {
-	mount: string
-	version: string
-}
-
-/**
- * @description Augment the '#imports' module to include useRuntimeConfig
- * this is only needed because this package is consumed as a module
- */
-declare module '#imports' {
-  export function useRuntimeConfig(): any
-}
+import { ModuleOptions } from '../dist/runtime/types.js';
+export * from '../dist/runtime/types.js';
 
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { type ClientFile, type ModuleOptions, type ServerFile, _default as default };
+export { _default as default };

package/dist/module.json

@@ -1,9 +1,9 @@
 {
   "name": "nuxt-file-storage",
   "configKey": "fileStorage",
-  "version": "0.3.1",
+  "version": "0.3.3-beta.0",
   "builder": {
-    "@nuxt/module-builder": "0.8.4",
-    "unbuild": "2.0.0"
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
   }
 }

package/dist/module.mjs

@@ -1,16 +1,7 @@
-import { defineNuxtModule, logger, createResolver, addImportsDir, addServerScanDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, logger, addImportsDir, addServerScanDir, addTemplate } from '@nuxt/kit';
 import { defu } from 'defu';
 
-
-
-// -- Unbuild CommonJS Shims --
-import __cjs_url__ from 'url';
-import __cjs_path__ from 'path';
-import __cjs_mod__ from 'module';
-const __filename = __cjs_url__.fileURLToPath(import.meta.url);
-const __dirname = __cjs_path__.dirname(__filename);
-const require = __cjs_mod__.createRequire(import.meta.url);
-const module = defineNuxtModule({
+const module$1 = defineNuxtModule({
   meta: {
     name: "nuxt-file-storage",
     configKey: "fileStorage"
@@ -21,15 +12,35 @@ const module = defineNuxtModule({
   // 	version: '0.0.0',
   // },
   setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
     const config = nuxt.options.runtimeConfig;
     config.public.fileStorage = defu(config.public.fileStorage, {
       ...options
     });
     logger.ready(`Nuxt File Storage has mounted successfully`);
-    const resolve = createResolver(__dirname).resolve;
+    nuxt.options.alias["#file-storage"] = resolve("./runtime");
     addImportsDir(resolve("runtime/composables"));
     addServerScanDir(resolve("./runtime/server"));
+    addTemplate({
+      filename: "types/nuxt-file-storage.d.ts",
+      getContents: () => [
+        "declare module '#file-storage' {",
+        `  const ServerFile: typeof import('${resolve("./runtime/types")}').ServerFile`,
+        `  const ClientFile: typeof import('${resolve("./runtime/types")}').ClientFile`,
+        "}",
+        "",
+        "declare global {",
+        `  type ServerFile = import('${resolve("./runtime/types")}').ServerFile`,
+        `  type ClientFile = import('${resolve("./runtime/types")}').ClientFile`,
+        "}",
+        "",
+        "export {}"
+      ].join("\n")
+    });
+    nuxt.hook("prepare:types", async (options2) => {
+      options2.references.push({ path: resolve(nuxt.options.buildDir, "types/nuxt-file-storage.d.ts") });
+    });
   }
 });
 
-export { module as default };
+export { module$1 as default };

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

@@ -1,39 +1,9 @@
-import type { ClientFile } from '../../types.js';
+import { type Ref } from 'vue';
 type Options = {
     clearOldFiles: boolean;
 };
 export default function (options?: Options): {
-    files: import("vue").Ref<{
-        content: string | {
-            readonly byteLength: number;
-            slice: (begin?: number, end?: number) => ArrayBuffer;
-            readonly [Symbol.toStringTag]: "ArrayBuffer";
-        } | null | undefined;
-        name: string;
-        lastModified: number;
-        readonly size: number;
-        readonly type: string;
-        arrayBuffer: () => Promise<ArrayBuffer>;
-        bytes: () => Promise<Uint8Array<ArrayBuffer>>;
-        slice: (start?: number, end?: number, contentType?: string) => Blob;
-        stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
-        text: () => Promise<string>;
-    }[], ClientFile[] | {
-        content: string | {
-            readonly byteLength: number;
-            slice: (begin?: number, end?: number) => ArrayBuffer;
-            readonly [Symbol.toStringTag]: "ArrayBuffer";
-        } | null | undefined;
-        name: string;
-        lastModified: number;
-        readonly size: number;
-        readonly type: string;
-        arrayBuffer: () => Promise<ArrayBuffer>;
-        bytes: () => Promise<Uint8Array<ArrayBuffer>>;
-        slice: (start?: number, end?: number, contentType?: string) => Blob;
-        stream: () => ReadableStream<Uint8Array<ArrayBuffer>>;
-        text: () => Promise<string>;
-    }[]>;
+    files: Ref<ClientFile[], ClientFile[]> & Iterable<ClientFile>;
     handleFileInput: (event: any) => Promise<void>;
     clearFiles: () => void;
 };

package/dist/runtime/composables/useFileStorage.js

@@ -1,6 +1,17 @@
 import { ref } from "vue";
+function createIterableRef(initialValue) {
+  const refObj = ref(initialValue);
+  Object.defineProperty(refObj, Symbol.iterator, {
+    value: function* () {
+      yield* refObj.value;
+    },
+    enumerable: false,
+    configurable: true
+  });
+  return refObj;
+}
 export default function(options = { clearOldFiles: true }) {
-  const files = ref([]);
+  const files = createIterableRef([]);
   const serializeFile = (file) => {
     return new Promise((resolve, reject) => {
       const reader = new FileReader();

package/dist/runtime/plugins/plugin.js

@@ -1,4 +1,4 @@
 import { defineNuxtPlugin } from "#app";
-export default defineNuxtPlugin((nuxtApp) => {
+export default defineNuxtPlugin((_nuxtApp) => {
   console.log("nuxt-file-storage initialized successfully");
 });

package/dist/runtime/server/utils/path-safety.js

@@ -2,42 +2,31 @@ import path from "path";
 import { realpath, stat } from "fs/promises";
 import { createError } from "#imports";
 export const normalizeRelative = (p) => {
-  if (!p)
-    return "";
+  if (!p) return "";
   return p.replace(/^[/\\]+/, "").replace(/\\/g, "/");
 };
 export const isSafeBasename = (name) => {
-  if (!name)
-    return false;
-  if (name !== path.basename(name))
-    return false;
-  if (name.includes("\0"))
-    return false;
-  if (name === "." || name === "..")
-    return false;
-  if (name.includes("/") || name.includes("\\"))
-    return false;
-  if (name.split(/[/\\]+/).includes(".."))
-    return false;
+  if (!name) return false;
+  if (name !== path.basename(name)) return false;
+  if (name.includes("\0")) return false;
+  if (name === "." || name === "..") return false;
+  if (name.includes("/") || name.includes("\\")) return false;
+  if (name.split(/[/\\]+/).includes("..")) return false;
   return true;
 };
 export const ensureSafeBasename = (name) => {
-  if (!isSafeBasename(name))
-    throw new Error("Unsafe filename");
+  if (!isSafeBasename(name)) throw new Error("Unsafe filename");
   return name;
 };
 export const containsPathTraversal = (p) => {
-  if (!p)
-    return false;
-  if (/^([\\/]|^)?\.\.([\\/]|$)?/.test(p) || /(^|[\\/])\.\.($|[\\/])/.test(p))
-    return true;
+  if (!p) return false;
+  if (/^([\\/]|^)?\.\.([\\/]|$)?/.test(p) || /(^|[\\/])\.\.($|[\\/])/.test(p)) return true;
   const normalized = path.normalize(p);
   const parts = normalized.split(/[/\\]+/);
   return parts.includes("..");
 };
 export const resolveAndEnsureInside = async (mount, ...parts) => {
-  if (!mount)
-    throw new Error("Mount path must be provided");
+  if (!mount) throw new Error("Mount path must be provided");
   const mountResolved = path.resolve(mount);
   const cleanedParts = parts.map((p) => p.replace(/^[/\\]+/, ""));
   const targetResolved = path.resolve(mountResolved, ...cleanedParts);
@@ -48,10 +37,9 @@ export const resolveAndEnsureInside = async (mount, ...parts) => {
       try {
         await stat(cur);
         break;
-      } catch (error) {
+      } catch {
         const parent = path.dirname(cur);
-        if (parent === cur)
-          break;
+        if (parent === cur) break;
         cur = parent;
       }
     }

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

@@ -1,4 +1,4 @@
-import type { ServerFile } from '../../../types.js';
+import type { ServerFile } from '../../types.js';
 import type { H3Event, EventHandlerRequest } from 'h3';
 /**
  * @description Will store the file in the specified directory

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

@@ -10,27 +10,50 @@ import { createReadStream, promises as fsPromises } from "fs";
 const getMount = () => {
   try {
     return useRuntimeConfig().public.fileStorage.mount;
-  } catch (err) {
+  } catch {
     return process.env.FILE_STORAGE_MOUNT || process.env.NUXT_FILE_STORAGE_MOUNT;
   }
 };
 export const storeFileLocally = async (file, fileNameOrIdLength, filelocation = "") => {
   const { binaryString, ext } = parseDataUrl(file.content);
   const location = getMount();
-  if (!location)
-    throw new Error("fileStorage.mount is not configured");
-  const originalExt = file.name.toString().split(".").pop() || ext;
-  const safeExt = originalExt.replace(/[^a-zA-Z0-9]/g, "") || ext;
+  if (!location) throw new Error("fileStorage.mount is not configured");
+  const nameStr = file.name.toString();
+  const originalExt = nameStr.includes(".") ? nameStr.split(".").pop() : ext;
+  const safeExt = (originalExt || ext).replace(/[^a-zA-Z0-9]/g, "") || ext;
   let filename;
   if (typeof fileNameOrIdLength === "number") {
     filename = `${generateRandomId(fileNameOrIdLength)}.${safeExt}`;
   } else {
     ensureSafeBasename(fileNameOrIdLength);
-    filename = `${fileNameOrIdLength}.${safeExt}`;
+    const extensionFromFileName = fileNameOrIdLength.split(".").pop();
+    if (!fileNameOrIdLength.includes(".")) {
+      filename = `${fileNameOrIdLength}.${safeExt}`;
+    } else if (extensionFromFileName === safeExt) {
+      filename = fileNameOrIdLength;
+    } else {
+      console.warn(
+        `[nuxt-file-storage] The provided filename "${fileNameOrIdLength}" does not have the expected extension ".${safeExt}". The correct extension will be appended.`
+      );
+      filename = `${fileNameOrIdLength.split(".").slice(0, -1).join(".")}.${safeExt}`;
+    }
   }
   const normalizedFilelocation = normalizeRelative(filelocation);
   const dirPath = await resolveAndEnsureInside(location, normalizedFilelocation);
-  await mkdir(dirPath, { recursive: true });
+  try {
+    await mkdir(dirPath, { recursive: true });
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      throw new Error(
+        `[nuxt-file-storage] EEXIST: A file already exists at "${dirPath}" where a directory was expected. This typically happens when a file was accidentally created at a path meant for a folder. Please remove or rename the conflicting file.`
+      );
+    } else if (err?.code === "ENOTDIR") {
+      throw new Error(
+        `[nuxt-file-storage] ENOTDIR: Cannot create directory "${dirPath}" because a parent path component is a file, not a directory. Check if any part of the path "${normalizedFilelocation}" exists as a file instead of a folder. Please remove or rename the conflicting file.`
+      );
+    }
+    throw err;
+  }
   const targetPath = await resolveAndEnsureInside(location, normalizedFilelocation, filename);
   await writeFile(targetPath, binaryString, {
     flag: "w"
@@ -39,8 +62,7 @@ export const storeFileLocally = async (file, fileNameOrIdLength, filelocation =
 };
 export const getFileLocally = (filename, filelocation = "") => {
   const location = getMount();
-  if (!location)
-    throw new Error("fileStorage.mount is not configured");
+  if (!location) throw new Error("fileStorage.mount is not configured");
   ensureSafeBasename(filename);
   const normalizedFilelocation = normalizeRelative(filelocation);
   const resolved = path.resolve(location, normalizedFilelocation, filename);
@@ -56,16 +78,14 @@ export const getFileLocally = (filename, filelocation = "") => {
 };
 export const getFilesLocally = async (filelocation = "") => {
   const location = getMount();
-  if (!location)
-    return [];
+  if (!location) return [];
   const normalizedFilelocation = normalizeRelative(filelocation);
   const dirPath = await resolveAndEnsureInside(location, normalizedFilelocation);
   return await readdir(dirPath).catch(() => []);
 };
 export const deleteFile = async (filename, filelocation = "") => {
   const location = getMount();
-  if (!location)
-    throw new Error("fileStorage.mount is not configured");
+  if (!location) throw new Error("fileStorage.mount is not configured");
   ensureSafeBasename(filename);
   const normalizedFilelocation = normalizeRelative(filelocation);
   const targetPath = await resolveAndEnsureInside(location, normalizedFilelocation, filename);
@@ -99,7 +119,7 @@ export const retrieveFileLocally = async (event, filename, filelocation = "") =>
     if (!stats.isFile()) {
       throw createError({ statusCode: 404, statusMessage: "Not Found" });
     }
-  } catch (err) {
+  } catch {
     throw createError({ statusCode: 404, statusMessage: "Not Found" });
   }
   const ext = path.extname(filePath).slice(1).toLowerCase();

package/dist/runtime/types.d.ts

@@ -0,0 +1,23 @@
+export interface ServerFile {
+    name: string;
+    content: string;
+    size: string;
+    type: string;
+    lastModified: string;
+}
+export interface ClientFile extends Blob {
+    content: string | ArrayBuffer | null | undefined;
+    name: string;
+    lastModified: number;
+}
+export interface ModuleOptions {
+    mount: string;
+    version: string;
+}
+/**
+ * @description Augment the '#imports' module to include useRuntimeConfig
+ * this is only needed because this package is consumed as a module
+ */
+declare module '#imports' {
+    function useRuntimeConfig(): any;
+}

package/dist/types.d.mts

@@ -1 +1,9 @@
-export { type useRuntimeConfig } from './module.js'
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'
+
+export * from '../dist/runtime/types.js'

package/package.json

@@ -1,22 +1,20 @@
 {
 	"name": "nuxt-file-storage",
-	"version": "0.3.1",
+	"version": "0.3.3-beta.0",
 	"description": "Easy solution to store files in your nuxt apps. Be able to upload files from the frontend and recieve them from the backend to then save the files in your project.",
-	"repository": "NyllRE/nuxt-file-storage",
 	"license": "MIT",
+	"repository": "NyllRE/nuxt-file-storage",
+	"files": [
+		"dist"
+	],
 	"type": "module",
+	"main": "./dist/module.mjs",
 	"exports": {
 		".": {
-			"types": "./dist/types.d.ts",
-			"import": "./dist/module.mjs",
-			"require": "./dist/module.cjs"
+			"types": "./dist/types.d.mts",
+			"import": "./dist/module.mjs"
 		}
 	},
-	"main": "./dist/module.cjs",
-	"types": "./dist/types.d.ts",
-	"files": [
-		"dist"
-	],
 	"scripts": {
 		"prepack": "nuxt-module-build build",
 		"dev": "nuxi dev playground",
@@ -24,27 +22,30 @@
 		"dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
 		"bump": "npm version patch -m \"chore(release): %s\"",
 		"release": "npm run lint && npm run bump && npm run prepack && changelogen && git push --follow-tags && npm publish",
-		"lint": "eslint .",
+		"lint": "oxlint .",
 		"test": "vitest run",
-		"test:watch": "vitest watch"
+		"test:watch": "vitest watch",
+		"test:ui": "vitest --ui",
+		"changelogen": "changelogen"
 	},
 	"dependencies": {
-		"@nuxt/kit": "^3.15.4",
+		"@nuxt/kit": "^4.3.0",
 		"defu": "^6.1.4"
 	},
 	"devDependencies": {
-		"@nuxt/devtools": "latest",
-		"@nuxt/eslint-config": "^0.2.0",
-		"@nuxt/module-builder": "^0.8.4",
-		"@nuxt/schema": "^3.15.4",
-		"@nuxt/test-utils": "^3.21.0",
+		"@nuxt/devtools": "^3.1.1",
+		"@nuxt/eslint-config": "^1.13.0",
+		"@nuxt/module-builder": "^1.0.2",
+		"@nuxt/schema": "^4.3.0",
+		"@nuxt/test-utils": "^4.0.0",
 		"@types/node": "^20.17.19",
 		"@vitest/ui": "4.0.16",
 		"@vue/test-utils": "^2.4.6",
 		"changelogen": "^0.5.7",
 		"eslint": "^8.57.1",
 		"happy-dom": "^20.0.11",
-		"nuxt": "^3.15.4",
+		"nuxt": "^4.3.0",
+		"oxlint": "^1.42.0",
 		"playwright-core": "^1.57.0",
 		"typescript": "^5.9.3",
 		"vitest": "^4.0.16"

package/dist/module.cjs

@@ -1,5 +0,0 @@
-module.exports = function(...args) {
-  return import('./module.mjs').then(m => m.default.call(this, ...args))
-}
-const _meta = module.exports.meta = require('./module.json')
-module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.ts

@@ -1,32 +0,0 @@
-import * as _nuxt_schema from '@nuxt/schema';
-
-interface ServerFile {
-	name: string
-	content: string
-	size: string
-	type: string
-	lastModified: string
-}
-
-interface ClientFile extends Blob {
-	content: string | ArrayBuffer | null | undefined
-	name: string
-	lastModified: number
-}
-
-interface ModuleOptions {
-	mount: string
-	version: string
-}
-
-/**
- * @description Augment the '#imports' module to include useRuntimeConfig
- * this is only needed because this package is consumed as a module
- */
-declare module '#imports' {
-  export function useRuntimeConfig(): any
-}
-
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
-
-export { type ClientFile, type ModuleOptions, type ServerFile, _default as default };

package/dist/types.d.ts

@@ -1 +0,0 @@
-export { type useRuntimeConfig } from './module'