Uploading Files

Warlock has two ways to upload files, either uploading a one or more files, or uploading a chunked file.

Uploading Files Directly

Let's start with uploading files directly, this is the most common way to upload files, it's used to upload images, videos, documents, and other types of files.

This request accepts the following request body:

type UploadRequestBody = {
  /**
   * List of uploaded files
   */
  uploads: UploadedFile[];
  /**
   * Directory to upload the file to
   *
   * @default Current date in the format of `DD-MM-YYYY`
   */
  directory?: string;
  /**
   * Whether to generate a random name for the file or not
   *
   * @default false
   */
  random?: boolean;
};

The uploads must be an array of uploaded files (Usually from the FormData object).

info

The uploads input is validated using required and file rules, make sure to import them in the Validation configurations.

The directory input is optional, it's used to specify the directory where the file will be uploaded to, if it's not specified, the directory will be the current date in the format of DD-MM-YYYY.

Whether directory is specified or not, the file will be uploaded to the uploads inside the storage directory.

tip

For each upload request, the upload directory will be extended with hash with length 64 directory to avoid conflicts between files with the same name.

An example of storing the uploaded file will be:

15 - 12 - 2023 / aDKOPQWEFVdskfwqpork312ewqdasq324aADADSF / my - image.png;

If the random input is set to true, the file name will be generated randomly but the file extension will be preserved.

Multipart Form Data

Please note that for time being, this request accepts only multipart/form-data content type.

Uploading Chunked Files

Chunked files are used to upload large files, it's used to upload videos, audio files, and other large files.

The scenario here is a little bit different than the previous one, the client will send a request to upload the file.

Let's see what data should be sent to the server for every chunk:

type ChunkedUploadRequestBody = {
  fileId: string;
  chunkNumber: number;
  chunk: UploadedFile;
  fileName: string;
  totalChunks: number;
  currentChunkSize: number;
  fileType: string;
};

The fileId is a unique identifier for the file, it's generated by the client and sent with the first chunk, it's used to identify the file and store it in a temporary memory buffer.

The chunkNumber is the current chunk number, it's used to identify the chunk and store it in the correct order.

The chunk is the uploaded file chunk content itself (Uploaded file).

The fileName is the file name, it's used to store the file in the correct order.

The totalChunks is the total number of chunks, it's used to identify the last chunk and store it in the correct order.

The currentChunkSize is the current chunk size, it's used to identify the last chunk and store it in the correct order.

The fileType is the mime type of the file.

The server will store the file in a temporary memory buffer, and when the last chunk is uploaded, the file will be moved to the storage directory and stored in the Uploads collection.

In the last chunk, the Upload output will be returned to the client, otherwise, it will return the chunk number.

Reuploading Chunks

Another great feature of using chunk uploads is the ability to reupload a chunk, this is useful when the client lost the internet connection or the server is down.

For each chunk uploaded file (Marked by fileId), it will be preserved from being deleted from the server for 24 hours, in simple words, the client has 24 hours to upload the entire file chunks.

Once the client uploads a chunk, the server will check if the chunk is already uploaded or not, if it's already uploaded, it will return the Upload output to the client, otherwise, it will return the chunk number.

tip

Any chunked file that is stored in the uploads collection, it will has chunked field with true to indicate that this file is uploaded using chunked upload.