Manage your Files with any Cloud Storage Services
Filesrocket is an package of Node.js that allows you to manage your files with any cloud storage service (Local, Cloudinary, Amazon S3) through the use of strategies called Services
⚠️ Filesrocket it is currently in beta phase. Note that it is not ready for production yet. Thanks for your understanding!❤️
🌈 Features
-
🔭 Manage your files with multiple cloud storage services (Cloudinary, Amazon S3, Local) -
✅ Validations (validate extensions, file sizes and more) -
⚡ Easy to configure and integrate -
🛡️ Written in Typescript - 👨🏻💻 Community driven
📖 Tutorial
Create a project
mkdir my-filesrocket-example
cd my-filesrocket-example
Configure the work environment
npm install typescript ts-node -g
npm init -y
tsc --init
Install the packages necessaries for start using Filesrocket
npm install express filesrocket filesrocket-local
npm install @types/express -D
Create a file src/index.ts in the root of the project
- Initialize app
import express from "express";
const app = express();
app.listen(3030, () => {
console.log("App execute in port:3030");
});- Register the services you are going to use
import { Filesrocket } from "filesrocket";
import { LocalFileService } from "filesrocket-local";
// Initialize
const filesrocket = new Filesrocket();
// Config your service
const service = new LocalFileService({
pagination: { default: 15, max: 50 },
host: "http://localhost:3030",
directory: "uploads",
});
// We register the service
filesrocket.register("local", service);- Register your endpoints.
const controller = filesrocket.controller("local");
// Create/Upload files.
app.post("/files", async (req, res) => {
const files = await controller.create(req, {});
res.status(200).json(files);
})
// List files.
app.get("/files", async (req, res) => {
const query = req.query;
const files = await controller.list(query);
res.status(200).json(files);
})
// Remove files.
app.delete("/files", async (req, res) => {
const query = req.query;
const { id } = query;
const files = await controller.remove(id, query)
res.status(200).json(files)
})Expose static files.
app.use("/uploads", express.static(path.resolve("uploads")));Note: By default there is no type of filter when uploading a file. Later we will see how to add validations, limit file sizes, fields and more...
We run the server
ts-node src/index.ts
With this simple example you can interact with the files, click on the following link: http://localhost:3030/files
🚀 Filesrocket
Filesrocket is a class that is in charge of orchestrating all the available functionalities; like registering services, getting them, forming controllers, etc.
Register services
In Filesrocket you can register multiple services to manage your files, the following example shows how to do it.
const filesrocket = new Filesrocket()
filesrocket.register("service-one", new MyOneService({...}))
filesrocket.register("service-two", new MyTwoService({...}))Recovering a service
To obtain a service, you do it in the following way. For more information about Services
const service = filesrocket.service("service-name")Recovering a controller
To obtain a controller, you do it in the following way. For more information about Controller
const controller = filesrocket.controller("service-name")Recovering all services
This property lists all the services that are registered
filesrocket.services
// [{ name, controller, service }]
🛎️ Services
Services are the heart of Filesrocket. In this chapter we will dive more into services.
In general, a service is an object or instance of a class that implements certain methods. Services provide a uniform, interface for how to interact with files.
Currently there are 3 services, but this is only the tip of the iceberg, later we will incorporate many more with your help.
| Service | Description |
|---|---|
| filesrocket-local | Manage your files on your own server. |
| filesrocket-cloudinary | Manage your files with Cloudinary |
| filesrocket-amazons3 | Manage your files with Amazon S3 |
Creating my first service
The official services may not meet your needs, but don't worry, Filesrocket is thinking for you to create your own services. So let's get to it. But before, it is necessary to take into account some considerations.
When you upload, list or delete a file, you will always get an entity with the following properties regardless of the service you are using
{
"id": "http://domain.com/image.png",
"name": "image.jpg",
"ext": ".jpg",
"url": "http://domain.com/image.png",
"size": 12345,
"dir": "",
"createdAt": "2022-03-08T20:09:07.958Z",
"updatedAt": "2022-03-08T20:09:07.958Z"
}Of course they open additional properties depending on the service, but these will be present at all times to avoid consistency problems or unexpected results.
Define a class
class MyService implements ServiceMethods {
async create(data: Data, query: Query): Promise<any> {
// ...
}
async list(query: Query): Promise<any> {
// ...
}
async remove(id: string, query: Query): Promise<any> {
// ...
}
}Register your service
filesrocket.register("my-service", new MyService({...}))Use via service
const service = filesrocket.service("my-service")Note: When you interact directly with the service, you have to parse the entire request, generate unique filenames.
Use via controller
const controller = filesrocket.controller("my-service")
🚩 Controller
A controller in Filesrocket is a class that is in charge of parsing the requests before invoking the Service. It basically works as an intermediary point for requests. Its responsibilities are the following:
- Interpret
multipart/form-datarequests. - Validate extensions, sizes, file numbers and other properties.
- Generate unique filenames.
Methods
Following is the list of methods on the class.
Create
This method is responsible for uploading the files to a certain service
const files = await controller.create(req, {});Every time you upload a file, Filesrocket will automatically generate unique filenames to avoid conflicts. For example:
one.jpg -> one-xakbsfak.jpgTo generate unique filenames, use Uniqid
Results
This method will return an array of the files that were just uploaded
[
{
"id": "http://domain.com/image.png",
"name": "image.jpg",
"ext": ".jpg",
"url": "http://domain.com/image.png",
"size": 12345,
"dir": "",
"createdAt": "2022-03-08T20:09:07.958Z",
"updatedAt": "2022-03-08T20:09:07.958Z"
}
]List
This method is responsible for listing files of a certain service
const files = await controller.list({});These properties will be present in all the services you use. There will be other properties that will be present depending on the service you are using.
Results
All official services will return paginated data.
{
"items": [],
"total": 0,
"size": 0,
"page": 1,
"nextPageToken": 2,
"prevPageToken": undefined
}Remove
This method is responsible for deleting files from a certain service. In order to delete a file, you have to send the id
const file = await controller.remove("abc");Result
In all official services the following structure will be returned. There will be additional properties depending on the service you are using
{
"id": "http://domain.com/image.png",
"name": "image.jpg",
"ext": ".jpg",
"url": "http://domain.com/image.png",
"size": 12345,
"dir": "",
"createdAt": "2022-03-08T20:09:07.958Z",
"updatedAt": "2022-03-08T20:09:07.958Z"
}
✅ Validations
You can also validate the file by specifying the rules for the extension, number and size of the files, and Filesrocket will perform the validations.
That validations will only be available in the controller. All properties except the
extnamesbelongs to Busboy, so we recommend you visit the documentation
const files = await controller.create(req, {
limits: { files: 5 },
extnames: [".jpg", ".png", ".jpeg"]
})When you upload files whose extension is not valid, Filesrocket will filter the files that do meet the extension.
👀 Examples
We've created some examples so you can clone it to your computer and get playing.
| Framework | Repository |
|---|---|
| Express | filesrocket-express-app |