library-manager-documents

:rocket: Table of Contents :rocket:

• Install
• Introduction
• Interfaces used
• Using methods
  • uploadDocument
  • getSignedDownloadUrl
  • replaceDocument
  • deleteDocument

Install

This is a Node.js module available through the npm registry.

Before installing, download and install Node.js. Node.js 0.6 or higher is required.

Installation is done using the npm install command:

$ npm install @therocketcodemx/library-manager-documents

Introduction

This library provides a simple way to manage documents, images, and videos stored in an Amazon Web Services (AWS) S3 bucket. It includes methods for uploading, downloading, deleting, and replacing files, as well as file type and size validation during upload.

Here is an example of how to initialize the module:

import { ManagerDocuments } from '@therocketcodemx/library-manager-documents';
// configuration object to connect to S3
const configS3 = {
  accessKeyId: "your-access-key-id",
  secretAccessKey: "your-secret-access-key",
  region: "your-region",
  bucket: "your-bucket",
  signatureVersion: "v4", // Optional
};
// The library uses the following default file types and sizes for validation during upload
const defaultFileTypesAndSizes = {
  document: {
    maxSize: 5000000, // in bytes
    allowedTypes: [".pdf", ".docx", ".xlsx", ".pptx", ".odt"],
  },
  image: {
    maxSize: 5000000, // in bytes
    allowedTypes: [".png", ".jpg", ".jpeg", ".gif"],
  },
  video: {
    maxSize: 20000000, // in bytes
    allowedTypes: [".mp4", ".avi", ".mov", ".wmv"],
  },
};
const manager = new ManagerDocuments(configS3, defaultFileTypesAndSizes);

...

You can provide an optional customFileTypesAndSizes object to the ManagerDocuments constructor to override the default file types and sizes used for validation during upload. The customFileTypesAndSizes object should have the same structure as the IFileTypeAndSize interface defined in the library.

Interfaces used

// The configuration object for AWS S3
interface IConfigS3 {
  accessKeyId: string; // Your AWS access key ID
  secretAccessKey: string; // Your AWS secret access key
  region: string; // The AWS region where your bucket is hosted
  bucket: string; // The name of your AWS S3 bucket
  signatureVersion?: string; // (optional) The AWS signature version you want to use. If not provided, the library will use 'v4' by default.
}
  // Enum defining the file types
enum FileType {
  DOCUMENT = "document",
  IMAGE = "image",
  VIDEO = "video",
  }
// Object containing max file sizes and allowed file types for each file type
interface IFileTypeAndSize {
  [FileType.DOCUMENT]?: {
    maxSize: number; // The maximum size, in bytes, of a document file that can be uploaded
    allowedTypes: string[]; // The file extensions that are accepted for document files
  };
  [FileType.IMAGE]?: {
    maxSize: number; // The maximum size, in bytes, of an image file that can be uploaded
    allowedTypes: string[]; // The file extensions that are accepted for image files
  };
  [FileType.VIDEO]?: {
    maxSize: number; // The maximum size, in bytes, of a video file that can be uploaded
    allowedTypes: string[]; // The file extensions that are accepted for video files
  };
}

Using methods

For use the methods the instance object is used of ManagerDocuments, for example:

uploadDocument

This method uploads a file to the S3 bucket. It takes a file buffer and a text string with the file name as parameters. If the file is invalid (for example, if it is too large or if its file type is not allowed), the method will throw an error.

// Example usage
const fileBuffer = Buffer.from('This is a file');
const fileName = 'location/for/the/file/my-file.pdf'; // This will be taken as the Key for the document

try {
  // The method returns a promise that resolves to the URL of the uploaded file
  const result = await manager.uploadDocument(fileBuffer, fileName);
  console.log(result); // "https://your-bucket.s3.your-region.amazonaws.com/location/of/the/file/my-file.pdf"
} catch (error) {
  console.error(error); // Handle the error
}

getSignedDownloadUrl

This method generates a presigned URL that allows access to a private S3 object. It takes a text string with the object key and an optional number specifying the time in seconds until the URL expires (default is 86400 seconds or 24 hours).

// Example usage
const key = 'location/of/the/file/my-file.pdf';
const expiresIn = 3600; // URL expires in 1 hour

const url = manager.getSignedDownloadUrl(key, expiresIn);
console.log(url); // "https://your-bucket.s3.your-region.amazonaws.com/location/of/the/file/my-file.pdf?token"

replaceDocument

This method is used to replace an existing file in the S3 bucket. It takes a buffer of the new file and a text string with the name of the file to be replaced as parameters. If the new file is invalid (for example, if it is too large or if its file type is not allowed), the method will throw an error.

// Example usage
const fileBuffer = Buffer.from('This is a new file');
const oldFileName = 'my-file.pdf'; // This will be taken as the Key for the document

try {
  // The method returns a promise that resolves to the URL of the replaced file
  const result = await manager.replaceDocument(fileBuffer, fileName);
  console.log(result);
} catch (error) {
  console.error(error);
}

deleteDocument

This method is used to delete a file by receiving as parameters: the name of the file to be deleted.

/ Example usage
const fileNameToDelete = 'location/for/the/file/my-file.pdf'; // This will be taken as the Key for the document

try {
  const result = await manager.deleteDocument(fileNameToDelete);
  console.log(result);
} catch (error) {
  console.error(error);
}