@nuvix/storage 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,469 @@
+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, type DeviceMetadata, File, FileExt, FileName, FileSize, FileType, Local, MinIO, S3, Storage, Upload, Wasabi };

package/dist/index.d.ts

@@ -466,5 +466,4 @@ declare class MinIO extends S3 {
     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 };
+export { Device, type DeviceMetadata, File, FileExt, FileName, FileSize, FileType, Local, MinIO, S3, Storage, Upload, Wasabi };