nuxt-file-storage 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-Present Nuxt File Storage Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+![Nuxt Storage Banner](./playground/public/nuxt-file-storage-banner.svg)
+
+# Nuxt File Storage
+
+[![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]
+
+
+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.
+
+-  [✨  Release Notes](/CHANGELOG.md)
+-  [🏀 Online playground](https://stackblitz.com/github/NyllRE/nuxt-file-storage?file=playground%2Fapp.vue)
+<!-- - [📖 &nbsp;Documentation](https://example.com) -->
+
+## Features
+
+<!-- Highlight some of the features your module provide here -->
+
+-  📁 &nbsp;Get files from file input and make them ready to send to backend
+-  ⚗️ &nbsp;Serialize files in the backend to be able to use them appropriately
+-  🖴 &nbsp;Store files in a specified location in your Nuxt backend with Nitro Engine
+
+## Quick Setup
+
+1. Add `nuxt-file-storage` dependency to your project
+
+```bash
+# Using pnpm
+pnpm add -D nuxt-file-storage
+
+# Using yarn
+yarn add --dev nuxt-file-storage
+
+# Using npm
+npm install --save-dev nuxt-file-storage
+```
+
+2. Add `nuxt-file-storage` to the `modules` section of `nuxt.config.ts`
+
+```js
+export default defineNuxtConfig({
+	modules: ['nuxt-file-storage'],
+})
+```
+
+That's it! You can now use Nuxt Storage in your Nuxt app ✨
+
+## Configuration
+
+You can currently configure a single setting of the `nuxt-file-storage` module. Here is the config interface:
+
+```js
+export default defineNuxtConfig({
+	modules: ['nuxt-file-storage'],
+	fileStorage: {
+		// enter the absolute path to the location of your storage
+		mount: '/home/$USR/development/nuxt-file-storage/server/files',
+
+		// {OR} use environment variables (recommended)
+		mount: process.env.mount
+		// you need to set the mount in your .env file at the root of your project
+	},
+})
+```
+
+## Usage
+
+### Handling Files in the frontend
+You can use Nuxt Storage to get the files from the `<input>` tag:
+
+```html
+<template>
+	<input type="file" @input="handleFileInput" />
+</template>
+
+<script setup>
+	// handleFileInput can handle multiple files
+	const { handleFileInput, files } = useFileStorage()
+</script>
+```
+The `files` return a ref object that contains the files
+
+Here's an example of using files to send them to the backend:
+```html
+<template>
+	<input type="file" @input="handleFileInput" />
+	<button @click="submit">submit</button>
+</template>
+
+<script setup>
+const { handleFileInput, files } = useFileStorage()
+
+const submit = async () => {
+	const response = await $fetch('/api/files', {
+		method: 'POST',
+		body: {
+			files: files.value
+		}
+	})
+}
+</script>
+```
+
+
+### Handling files in the backend
+using Nitro Server Engine, we will make an api route that recieves the files and stores them in the folder `userFiles`
+```ts
+export default defineEventHandler(async (event) => {
+	const { file } = await readBody<{ file: File }>(event)
+
+	await storeFileLocally(
+		file.content, // the stringified version of the file
+		file.name,    // the name of the file
+		'/userFiles'  // the folder the file will be stored in
+	)
+
+	// {OR}
+
+	// Parses a data URL and returns an object with the binary data and the file extension.
+	const { binaryString, ext } = parseDataUrl(file.content)
+
+	return 'success!'
+})
+
+interface File {
+	name: string
+	content: string
+}
+```
+
+And that's it! Now you can store any file in your nuxt project from the user ✨
+
+## Contribution
+Run into a problem? Open a [new issue](https://github.com/NyllRE/nuxt-file-storage/issues/new). I'll try my best to include all the features requested if it is fitting to the scope of the project.
+
+Want to add some feature? PRs are welcome!
+- Clone this repository
+- install the dependencies
+- prepare the project
+- run dev server
+```bash
+git clone https://github.com/NyllRE/nuxt-file-storage && cd nuxt-file-storage
+npm i
+npm run dev:prepare
+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
+[nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.cjs

@@ -0,0 +1,5 @@
+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.mts

@@ -0,0 +1,8 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    mount: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions>;
+
+export { type ModuleOptions, _default as default };

package/dist/module.d.ts

@@ -0,0 +1,8 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    mount: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions>;
+
+export { type ModuleOptions, _default as default };

package/dist/module.json

@@ -0,0 +1,5 @@
+{
+  "name": "nuxt-file-storage",
+  "configKey": "fileStorage",
+  "version": "0.2.0"
+}

package/dist/module.mjs

@@ -0,0 +1,25 @@
+import { defineNuxtModule, createResolver, addImportsDir } from '@nuxt/kit';
+import defu from 'defu';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-file-storage",
+    configKey: "fileStorage"
+  },
+  //? Default configuration options of the Nuxt module
+  // defaults: {
+  // },
+  setup(options, nuxt) {
+    nuxt.options.runtimeConfig.public.fileStorage = defu(
+      nuxt.options.runtimeConfig.public.fileStorage,
+      {
+        ...options
+      }
+    );
+    const resolver = createResolver(import.meta.url);
+    addImportsDir(resolver.resolve("runtime/composables"));
+    addImportsDir(resolver.resolve("runtime/server/utils"));
+  }
+});
+
+export { module as default };

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

@@ -0,0 +1,13 @@
+export default function (): {
+    files: import("vue").Ref<{
+        content: any;
+        name: string;
+        readonly size: number;
+        readonly type: string;
+        arrayBuffer: () => Promise<ArrayBuffer>;
+        slice: (start?: number | undefined, end?: number | undefined, contentType?: string | undefined) => Blob;
+        stream: () => ReadableStream<Uint8Array>;
+        text: () => Promise<string>;
+    }[]>;
+    handleFileInput: (event: any) => void;
+};

package/dist/runtime/composables/useFileStorage.mjs

@@ -0,0 +1,25 @@
+import { ref } from "vue";
+export default function() {
+  const files = ref([]);
+  const serializeFile = (file) => {
+    const reader = new FileReader();
+    reader.onload = (e) => {
+      files.value.push({
+        ...file,
+        content: e.target.result
+      });
+    };
+    reader.readAsDataURL(file);
+  };
+  const handleFileInput = (event) => {
+    files.value.splice(0);
+    console.log("handleFileInput event: " + event);
+    for (const file of event.target.files) {
+      serializeFile(file);
+    }
+  };
+  return {
+    files,
+    handleFileInput
+  };
+}

package/dist/runtime/plugins/plugin.d.ts

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

package/dist/runtime/plugins/plugin.mjs

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

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

@@ -0,0 +1,16 @@
+/// <reference types="node" />
+/**
+ * @returns mime type
+ * @prop fileNameOrIdLength: you can pass a string or a number, if you enter a string it will be the file name, if you enter a number it will generate a unique ID
+ */
+export declare const storeFileLocally: (dataurl: string, fileNameOrIdLength: string | number, filelocation?: string) => Promise<string>;
+export declare const deleteFile: (filename: string, filelocation?: string) => Promise<void>;
+/**
+Parses a data URL and returns an object with the binary data and the file extension.
+@param {string} file - The data URL
+@returns {{ binaryString: Buffer, ext: string }} - An object with the binary data and the file extension
+ */
+export declare const parseDataUrl: (file: string) => {
+    binaryString: Buffer;
+    ext: any;
+};

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

@@ -0,0 +1,36 @@
+import mimeTypes from "mime-types";
+import { writeFile, rm, mkdir } from "fs/promises";
+export const storeFileLocally = async (dataurl, fileNameOrIdLength, filelocation = "") => {
+  const { binaryString, ext } = parseDataUrl(dataurl);
+  const location = useRuntimeConfig().public.fileStorage.mount;
+  const filename = typeof fileNameOrIdLength == "number" ? generateRandomId(fileNameOrIdLength) : fileNameOrIdLength;
+  await mkdir(`${location}${filelocation}`, { recursive: true });
+  await writeFile(`${location}${filelocation}/${filename}.${ext}`, binaryString, {
+    flag: "w"
+  });
+  return `${filename}.${ext}`;
+};
+export const deleteFile = async (filename, filelocation = "") => {
+  const location = useRuntimeConfig().public.fileStorage.mount;
+  await rm(`${location}${filelocation}/${filename}`);
+};
+const generateRandomId = (length) => {
+  const characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+  let randomId = "";
+  for (let i = 0; i < length; i++) {
+    randomId += characters.charAt(Math.floor(Math.random() * characters.length));
+  }
+  return randomId;
+};
+export const parseDataUrl = (file) => {
+  const arr = file.split(",");
+  const mimeMatch = arr[0].match(/:(.*?);/);
+  if (!mimeMatch) {
+    throw new Error("Invalid data URL");
+  }
+  const mime = mimeMatch[1];
+  const base64String = arr[1];
+  const binaryString = Buffer.from(base64String, "base64");
+  const ext = mimeTypes.extension(mime);
+  return { binaryString, ext };
+};

package/dist/types.d.mts

@@ -0,0 +1,16 @@
+
+import type { ModuleOptions } from './module.js'
+
+
+declare module '@nuxt/schema' {
+  interface NuxtConfig { ['fileStorage']?: Partial<ModuleOptions> }
+  interface NuxtOptions { ['fileStorage']?: ModuleOptions }
+}
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig { ['fileStorage']?: Partial<ModuleOptions> }
+  interface NuxtOptions { ['fileStorage']?: ModuleOptions }
+}
+
+
+export type { ModuleOptions, default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+
+import type { ModuleOptions } from './module'
+
+
+declare module '@nuxt/schema' {
+  interface NuxtConfig { ['fileStorage']?: Partial<ModuleOptions> }
+  interface NuxtOptions { ['fileStorage']?: ModuleOptions }
+}
+
+declare module 'nuxt/schema' {
+  interface NuxtConfig { ['fileStorage']?: Partial<ModuleOptions> }
+  interface NuxtOptions { ['fileStorage']?: ModuleOptions }
+}
+
+
+export type { ModuleOptions, default } from './module'

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "nuxt-file-storage",
+	"version": "0.2.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",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/types.d.ts",
+			"import": "./dist/module.mjs",
+			"require": "./dist/module.cjs"
+		}
+	},
+	"main": "./dist/module.cjs",
+	"types": "./dist/types.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"prepack": "nuxt-module-build build",
+		"dev": "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"
+	},
+	"dependencies": {
+		"@nuxt/kit": "^3.9.3",
+		"defu": "^6.1.4"
+	},
+	"devDependencies": {
+		"@nuxt/devtools": "latest",
+		"@nuxt/eslint-config": "^0.2.0",
+		"@nuxt/module-builder": "^0.5.5",
+		"@nuxt/schema": "^3.9.3",
+		"@nuxt/test-utils": "^3.9.0",
+		"@types/mime-types": "^2.1.4",
+		"@types/node": "^20.11.5",
+		"changelogen": "^0.5.5",
+		"eslint": "^8.56.0",
+		"mime-types": "^2.1.35",
+		"nuxt": "^3.9.3",
+		"vitest": "^1.0.0"
+	}
+}