@nuvix/storage/dist/index.d.ts

S3-compatible storage library for Nuvix BaaS platform with support for AWS S3, Wasabi, MinIO, and local storage

interface DeviceMetadata {
    [key: string]: any;
}
declare abstract class Device {
    /**
     * Max chunk size while transferring file from one device to another
     */
    protected transferChunkSize: number;
    /**
     * Sets the maximum number of keys returned to the response. By default, the action returns up to 1,000 key names.
     */
    protected static readonly MAX_PAGE_SIZE: number;
    /**
     * Set Transfer Chunk Size
     */
    setTransferChunkSize(chunkSize: number): void;
    /**
     * Get Transfer Chunk Size
     */
    getTransferChunkSize(): number;
    /**
     * Get Name.
     *
     * Get storage device name
     */
    abstract getName(): string;
    /**
     * Get Type.
     *
     * Get storage device type
     */
    abstract getType(): string;
    /**
     * Get Description.
     *
     * Get storage device description and purpose.
     */
    abstract getDescription(): string;
    /**
     * Get Root.
     *
     * Get storage device root path
     */
    abstract getRoot(): string;
    /**
     * Get Path.
     *
     * Each device hold a complex directory structure that is being build in this method.
     */
    abstract getPath(filename: string, prefix?: string): string;
    /**
     * Upload.
     *
     * Upload a file to desired destination in the selected disk
     * return number of chunks uploaded or 0 if it fails.
     */
    abstract upload(source: string, path: string, chunk?: number, chunks?: number, metadata?: DeviceMetadata): Promise<number>;
    /**
     * Upload Data.
     *
     * Upload file contents to desired destination in the selected disk.
     * return number of chunks uploaded or 0 if it fails.
     */
    abstract uploadData(data: string | Buffer, path: string, contentType: string, chunk?: number, chunks?: number, metadata?: DeviceMetadata): Promise<number>;
    /**
     * Abort Chunked Upload
     */
    abstract abort(path: string, extra?: string): Promise<boolean>;
    /**
     * Read file by given path.
     */
    abstract read(path: string, offset?: number, length?: number): Promise<Buffer>;
    /**
     * Transfer
     * Transfer a file from current device to destination device.
     */
    abstract transfer(path: string, destination: string, device: Device): Promise<boolean>;
    /**
     * Write file by given path.
     */
    abstract write(path: string, data: string | Buffer, contentType: string): Promise<boolean>;
    /**
     * Move file from given source to given path, return true on success and false on failure.
     */
    move(source: string, target: string): Promise<boolean>;
    /**
     * Delete file in given path return true on success and false on failure.
     */
    abstract delete(path: string, recursive?: boolean): Promise<boolean>;
    /**
     * Delete files in given path, path must be a directory. return true on success and false on failure.
     */
    abstract deletePath(path: string): Promise<boolean>;
    /**
     * Check if file exists
     */
    abstract exists(path: string): Promise<boolean>;
    /**
     * Returns given file path its size.
     */
    abstract getFileSize(path: string): Promise<number>;
    /**
     * Returns given file path its mime type.
     */
    abstract getFileMimeType(path: string): Promise<string>;
    /**
     * Returns given file path its MD5 hash value.
     */
    abstract getFileHash(path: string): Promise<string>;
    /**
     * Create a directory at the specified path.
     *
     * Returns true on success or if the directory already exists and false on error
     */
    abstract createDirectory(path: string): Promise<boolean>;
    /**
     * Get directory size in bytes.
     *
     * Return -1 on error
     */
    abstract getDirectorySize(path: string): Promise<number>;
    /**
     * Get Partition Free Space.
     *
     * Returns available space on filesystem or disk partition
     */
    abstract getPartitionFreeSpace(): Promise<number>;
    /**
     * Get Partition Total Space.
     *
     * Returns the total size of a filesystem or disk partition
     */
    abstract getPartitionTotalSpace(): Promise<number>;
    /**
     * Get all files and directories inside a directory.
     */
    abstract getFiles(dir: string, max?: number, continuationToken?: string): Promise<any[]>;
    /**
     * Get the absolute path by resolving strings like ../, .., //, /\ and so on.
     *
     * Works like the realpath function but works on files that does not exist
     */
    getAbsolutePath(path: string): string;
    protected getMimeType(filePath: string): Promise<string>;
}

declare class Storage {
    /**
     * Supported devices
     */
    static readonly DEVICE_LOCAL = "local";
    static readonly DEVICE_S3 = "s3";
    static readonly DEVICE_WASABI = "wasabi";
    static readonly DEVICE_MINIO = "minio";
    /**
     * Devices.
     *
     * List of all available storage devices
     */
    private static devices;
    /**
     * Set Device.
     *
     * Add device by name
     *
     * @param name
     * @param device
     * @throws Error
     */
    static setDevice(name: string, device: Device): void;
    /**
     * Get Device.
     *
     * Get device by name
     *
     * @param name
     * @returns Device
     * @throws Error
     */
    static getDevice(name: string): Device;
    /**
     * Exists.
     *
     * Checks if given storage name is registered or not
     *
     * @param name
     * @returns boolean
     */
    static exists(name: string): boolean;
    /**
     * Human readable data size format from bytes input.
     *
     * Based on: https://stackoverflow.com/a/38659168/2299554
     *
     * @param bytes
     * @param decimals
     * @param system
     * @returns string
     */
    static human(bytes: number, decimals?: number, system?: "binary" | "metric"): string;
}

declare abstract class Validator {
    static TYPE_STRING: string;
    static TYPE_ARRAY: string;
    static TYPE_INTEGER: string;
    static TYPE_BOOLEAN: string;
    abstract isValid(value: any): boolean | Promise<boolean>;
}

declare class File extends Validator {
    getDescription(): string;
    /**
     * NOT MUCH RIGHT NOW.
     *
     * TODO think what to do here, currently only used for parameter to be present in SDKs
     *
     * @param name
     * @return boolean
     */
    isValid(name: any): boolean;
}

declare class FileExt extends Validator {
    static readonly TYPE_JPEG = "jpeg";
    static readonly TYPE_JPG = "jpg";
    static readonly TYPE_GIF = "gif";
    static readonly TYPE_PNG = "png";
    static readonly TYPE_GZIP = "gz";
    static readonly TYPE_ZIP = "zip";
    private allowed;
    constructor(allowed: string[]);
    getDescription(): string;
    isValid(filename: string): boolean;
    private getFileExtension;
}

declare class FileName extends Validator {
    /**
     * Get Description
     */
    getDescription(): string;
    /**
     * The file name can only contain "a-z", "A-Z", "0-9" and "." and not empty.
     *
     * @param name - The filename to validate
     * @returns boolean indicating if the filename is valid
     */
    isValid(name: any): boolean;
}

declare class FileSize extends Validator {
    private max;
    /**
     * Max size in bytes
     */
    constructor(max: number);
    /**
     * Get Description
     */
    getDescription(): string;
    /**
     * Finds whether a file size is smaller than required limit.
     */
    isValid(fileSize: any): boolean;
}

declare class FileType extends Validator {
    /**
     * File Types Constants.
     */
    static readonly FILE_TYPE_JPEG = "jpeg";
    static readonly FILE_TYPE_GIF = "gif";
    static readonly FILE_TYPE_PNG = "png";
    static readonly FILE_TYPE_GZIP = "gz";
    /**
     * File Type Binaries.
     */
    private readonly types;
    private readonly allowed;
    constructor(allowed: string[]);
    /**
     * Get Description
     */
    getDescription(): string;
    /**
     * Is Valid.
     *
     * Binary check to finds whether a file is of valid type
     */
    isValid(path: string): Promise<boolean>;
}

declare class Upload extends Validator {
    /**
     * Get Description
     */
    getDescription(): string;
    /**
     * Check if a file is a valid upload file
     *
     * @param path - The file path to validate
     * @returns Promise that resolves to true if valid upload file, false otherwise
     */
    isValid(path: unknown): Promise<boolean>;
}

declare class Local extends Device {
    protected root: string;
    protected readonly MAX_PAGE_SIZE = 1000;
    constructor(root?: string);
    getName(): string;
    getType(): string;
    getDescription(): string;
    getRoot(): string;
    getPath(filename: string, prefix?: string): string;
    upload(source: string, filePath: string, chunk?: number, chunks?: number, metadata?: Record<string, any>): Promise<number>;
    uploadData(data: string | Buffer, filePath: string, contentType: string, chunk?: number, chunks?: number, metadata?: Record<string, any>): Promise<number>;
    private joinChunks;
    transfer(filePath: string, destination: string, device: Device): Promise<boolean>;
    abort(filePath: string, extra?: string): Promise<boolean>;
    read(filePath: string, offset?: number, length?: number): Promise<Buffer>;
    write(filePath: string, data: string | Buffer, contentType?: string): Promise<boolean>;
    move(source: string, target: string): Promise<boolean>;
    delete(filePath: string, recursive?: boolean): Promise<boolean>;
    deletePath(filePath: string): Promise<boolean>;
    exists(filePath: string): Promise<boolean>;
    getFileSize(filePath: string): Promise<number>;
    getFileMimeType(filePath: string): Promise<string>;
    getFileHash(filePath: string): Promise<string>;
    createDirectory(dirPath: string): Promise<boolean>;
    getDirectorySize(dirPath: string): Promise<number>;
    getPartitionFreeSpace(): Promise<number>;
    getPartitionTotalSpace(): Promise<number>;
    getFiles(dir: string, max?: number, continuationToken?: string): Promise<string[]>;
}

declare class S3 extends Device {
    static readonly METHOD_GET = "GET";
    static readonly METHOD_POST = "POST";
    static readonly METHOD_PUT = "PUT";
    static readonly METHOD_PATCH = "PATCH";
    static readonly METHOD_DELETE = "DELETE";
    static readonly METHOD_HEAD = "HEAD";
    static readonly METHOD_OPTIONS = "OPTIONS";
    static readonly METHOD_CONNECT = "CONNECT";
    static readonly METHOD_TRACE = "TRACE";
    static readonly US_EAST_1 = "us-east-1";
    static readonly US_EAST_2 = "us-east-2";
    static readonly US_WEST_1 = "us-west-1";
    static readonly US_WEST_2 = "us-west-2";
    static readonly AF_SOUTH_1 = "af-south-1";
    static readonly AP_EAST_1 = "ap-east-1";
    static readonly AP_SOUTH_1 = "ap-south-1";
    static readonly AP_NORTHEAST_3 = "ap-northeast-3";
    static readonly AP_NORTHEAST_2 = "ap-northeast-2";
    static readonly AP_NORTHEAST_1 = "ap-northeast-1";
    static readonly AP_SOUTHEAST_1 = "ap-southeast-1";
    static readonly AP_SOUTHEAST_2 = "ap-southeast-2";
    static readonly CA_CENTRAL_1 = "ca-central-1";
    static readonly EU_CENTRAL_1 = "eu-central-1";
    static readonly EU_WEST_1 = "eu-west-1";
    static readonly EU_SOUTH_1 = "eu-south-1";
    static readonly EU_WEST_2 = "eu-west-2";
    static readonly EU_WEST_3 = "eu-west-3";
    static readonly EU_NORTH_1 = "eu-north-1";
    static readonly SA_EAST_1 = "eu-north-1";
    static readonly CN_NORTH_1 = "cn-north-1";
    static readonly CN_NORTH_4 = "cn-north-4";
    static readonly CN_NORTHWEST_1 = "cn-northwest-1";
    static readonly ME_SOUTH_1 = "me-south-1";
    static readonly US_GOV_EAST_1 = "us-gov-east-1";
    static readonly US_GOV_WEST_1 = "us-gov-west-1";
    static readonly ACL_PRIVATE = "private";
    static readonly ACL_PUBLIC_READ = "public-read";
    static readonly ACL_PUBLIC_READ_WRITE = "public-read-write";
    static readonly ACL_AUTHENTICATED_READ = "authenticated-read";
    protected static readonly MAX_PAGE_SIZE = 1000;
    protected static retryAttempts: number;
    protected static retryDelay: number;
    protected accessKey: string;
    protected secretKey: string;
    protected bucket: string;
    protected region: string;
    protected acl: string;
    protected root: string;
    protected headers: Record<string, string>;
    protected amzHeaders: Record<string, string>;
    constructor(root: string, accessKey: string, secretKey: string, bucket: string, region?: string, acl?: string, endpointUrl?: string);
    getName(): string;
    getType(): string;
    getDescription(): string;
    getRoot(): string;
    getPath(filename: string, prefix?: string): string;
    getPartitionTotalSpace(): Promise<number>;
    static setRetryAttempts(attempts: number): void;
    static setRetryDelay(delay: number): void;
    upload(source: string | Buffer, path: string, chunk?: number, chunks?: number, metadata?: Record<string, any>): Promise<number>;
    uploadData(data: Buffer, path: string, contentType: string, chunk?: number, chunks?: number, metadata?: Record<string, any>): Promise<number>;
    transfer(path: string, destination: string, device: Device): Promise<boolean>;
    protected createMultipartUpload(path: string, contentType: string): Promise<string>;
    protected uploadPart(data: Buffer, path: string, contentType: string, chunk: number, uploadId: string): Promise<string>;
    protected completeMultipartUpload(path: string, uploadId: string, parts: Record<number, string>): Promise<boolean>;
    abort(path: string, extra?: string): Promise<boolean>;
    read(path: string, offset?: number, length?: number): Promise<Buffer>;
    write(path: string, data: Buffer, contentType?: string): Promise<boolean>;
    delete(path: string, recursive?: boolean): Promise<boolean>;
    protected listObjects(prefix?: string, maxKeys?: number, continuationToken?: string): Promise<any>;
    deletePath(path: string): Promise<boolean>;
    exists(path: string): Promise<boolean>;
    getFileSize(path: string): Promise<number>;
    getFileMimeType(path: string): Promise<string>;
    getFileHash(path: string): Promise<string>;
    createDirectory(path: string): Promise<boolean>;
    getDirectorySize(path: string): Promise<number>;
    getPartitionFreeSpace(): Promise<number>;
    getFiles(dir: string, max?: number, continuationToken?: string): Promise<any>;
    private getInfo;
    protected getSignatureV4(method: string, uri: string, parameters?: Record<string, string>): string;
    protected call(method: string, uri: string, data?: string | Buffer, parameters?: Record<string, string>, decode?: boolean): Promise<{
        body: any;
        buffer: ArrayBuffer;
        headers: Record<string, string>;
        code: number;
    }>;
    protected md5(data: string | Buffer): Buffer;
    protected sha256(data: string | Buffer): string;
    protected hmacSha256(data: string | Buffer, key: string | Buffer, encoding?: "hex" | "binary"): string | Buffer;
}

declare class Wasabi extends S3 {
    /**
     * Regions constants
     */
    static readonly US_WEST_1 = "us-west-1";
    static readonly AP_NORTHEAST_1 = "ap-northeast-1";
    static readonly AP_NORTHEAST_2 = "ap-northeast-2";
    static readonly EU_CENTRAL_1 = "eu-central-1";
    static readonly EU_CENTRAL_2 = "eu-central-2";
    static readonly EU_WEST_1 = "eu-west-1";
    static readonly EU_WEST_2 = "eu-west-2";
    static readonly US_CENTRAL_1 = "us-central-1";
    static readonly US_EAST_1 = "us-east-1";
    static readonly US_EAST_2 = "us-east-2";
    /**
     * Wasabi Constructor
     */
    constructor(root: string, accessKey: string, secretKey: string, bucket: string, region?: string, acl?: string);
    getName(): string;
    getDescription(): string;
    getType(): string;
}

declare class MinIO extends S3 {
    /**
     * MinIO Constructor
     */
    constructor(root: string, accessKey: string, secretKey: string, bucket: string, endpoint?: string, acl?: string, useSSL?: boolean);
    private endpointUrl;
    getName(): string;
    getDescription(): string;
    getType(): string;
    /**
     * Override the call method to use the custom endpoint
     */
    protected call(method: string, uri: string, data?: string | Buffer, parameters?: Record<string, string>, decode?: boolean): Promise<any>;
}

export { Device, File, FileExt, FileName, FileSize, FileType, Local, MinIO, S3, Storage, Upload, Wasabi };
export type { DeviceMetadata };