@andreashauschild/just-upload v1.1.0

just-upload

Just Upload is an angular library (without external dependencies) that provides all necessary features to make file upload simple as possible. The goal of the library is to provide services , models and examples to implement your own custom upload components.

Requires: Angular 13+

Info The developer provides a backend service (quarkus) to execute real file uploads. Files send to this api will be deleted after upload. Endpoint: https://just-upload.litexo.de

Features

• Includes Hooks to enrich/customize request data like query parameters and headers (e.g. access tokens)
• Supports different upload types:
  • Basic Upload - send file as application/octet-stream
    • see Basic Upload Example
    • Quarkus Endpoint (BasicUploadResource.java)
  • Basic Upload Multipart - uploads files as multipart/form-data
    • see Basic Multipart Example
    • Quarkus Endpoint (BasicUploadResource.java)
  • Chunked Upload - Splits a file in chunks and sends for each chunk a http request. This can be used to upload very large files which may exceeding the size limit of a single request.
    • see Basic Chunked Upload Example
    • Quarkus Endpoint (ChunkUploadResource.java)
• Provides a lot of useful information out of the box
  • State update via Observables while uploading
  • State of upload in percent
  • Size of file in a human-readable format (KB, MB, GB)
  • MimeType recognition
  • Example of data model:
  • 

Installation

npm install @andreashauschild/just-upload

Usage

To use this library you need to import the JustUploadModule into your application. After that you can use the JustUploadService in your components.

Import the JustUploadModule

Import it in your angular app.module.ts. Furthermore, the HttpClientModule from @angular/common/http must also be imported.

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    HttpClientModule,
    JustUploadModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {
}

Inject the Service in your Component

constructor(private service: JustUploadService)

Concepts - Basic Upload

The JustUploadService helps you to create an upload object which provides all necessary functions to implement your upload. To create an upload you need to provide a reference to a HTML file input element and a configuration.

After the creation of the upload object you can listen to changes if you subscribe to onFileProcessed and onFiledAdded.

The most simple upload looks like this (The code can be found here: example1):

Info the backend of the upload server is implemented in java with quarkus. You can find the REST-Endpoint here: BasicUploadResource.java

import {AfterViewInit, Component, ElementRef, ViewChild} from '@angular/core';
import {JustUploadService, Upload, UploadConfig} from 'just-upload';

@Component({
  selector: 'app-documentation1',
  template: `
    <!-- HTML File Input with template variables as reference    -->
    <input #fileUpload type="file">
  `,
  styles: [``]
})
export class Documentation1Component implements AfterViewInit {

  // Element reference of the file input field. Be aware that this ref will be accessible in AfterViewInit
  @ViewChild("fileUpload", {static: false})
  fileUpload: ElementRef | undefined;

  // The config for the upload
  config: UploadConfig;

  // The upload object which controls everything
  upload?: Upload;

  constructor(private service: JustUploadService) {
    // initialize basic config this will send the file immediately to the given endpoint with a post request
    this.config = {
      url: "https://just-upload.litexo.de/api/basic-upload/single-binary",
      method: "POST"
    }
  }

  // Use ngAfterViewInit because in the lifecycle step the 'upload' is set
  ngAfterViewInit(): void {

    // Setup the upload
    this.upload = this.service.createUpload(this.fileUpload!, this.config);

    // Log the processing stages of the file
    this.upload.onFileProcessed().subscribe(procced => {
      console.log("File Processed", procced);
    });

    // Log if a file was added to the upload
    this.upload.onFiledAdded().subscribe(added => {
      console.log("File Added", added);
    });
  }

}

UploadConfig - UploadFile - Upload & MultipartFormUpload

• Basic Upload Example

• Quarkus Endpoint (BasicUploadResource.java)

• Basic Multipart Example

• Quarkus Endpoint (BasicUploadResource.java)

UploadConfig

The UploadConfig allows the following configurations:

UploadFile

The UploadFile is the file data model. It holds the browser file and additional information:

Upload & MultipartFormUpload

The Upload and MultipartFormUpload will be created by a factory method of the JustUploadService. It is the main object you will work with. In case of MultipartFormUpload every file will be sent as single multipart/form-data request. This means if you have 5 files in your file list, they will be sent in 5 separate requests. If you use Upload every file will be sent as an application/octet-stream to the server.

ChunkedUploadConfig - ChunkedUploadFile - ChunkedUpload

Chunked Upload - Splits a file in chunks and sends for each chunk a http request. This can be used to upload very large files which may exceeding the size of a single request.

• see Basic Chunked Upload Example
• Quarkus Endpoint (ChunkUploadResource.java)

The ChunkedUploadConfig allows the following configurations:

ChunkedUploadFile & FileChunk

The ChunkedUploadFile represents the file that is uploaded an FileChunk represents a chunk of this file. It holds the browser file and additional information:

ChunkedUploadFile

ChunkedUploadFile

ChunkedUpload

The ChunkedUpload will be created by a factory method of the JustUploadService. It is the main object you will work with. Every chunk will be sent as an application/octet-stream to the server.