@uploadx/core/lib/storages/storage.d.ts

Node.js resumable upload middleware

import { IncomingMessage, UploadxResponse } from '../types';
import { Cache, ErrorResponses, HttpError, HttpErrorBody, Locker, Logger, LogLevel, Validation, Validator } from '../utils';
import { File, FileInit, FilePart, FileQuery } from './file';
import { MetaStorage, UploadList } from './meta-storage';
export type UserIdentifier = (req: any, res: any) => string;
export type OnCreate<TFile extends File, TBody = any> = (file: TFile) => Promise<TBody> | TBody;
export type OnUpdate<TFile extends File, TBody = any> = (file: TFile) => Promise<TBody> | TBody;
export type OnComplete<TFile extends File, TBody = any> = (file: TFile) => Promise<TBody> | TBody;
export type OnDelete<TFile extends File, TBody = any> = (file: TFile) => Promise<TBody> | TBody;
export type OnError<TBody = HttpErrorBody> = (error: HttpError<TBody>) => any;
export type PurgeList = UploadList & {
    maxAgeMs: number;
};
export interface ExpirationOptions {
    /**
     * Age of the upload, after which it is considered expired and can be deleted
     */
    maxAge: number | string;
    /**
     * Auto purging interval for expired uploads
     */
    purgeInterval?: number | string;
    /**
     * Auto prolong expiring uploads
     */
    rolling?: boolean;
}
export interface BaseStorageOptions<T extends File> {
    /** Allowed MIME types */
    allowMIME?: string[];
    /** File size limit */
    maxUploadSize?: number | string;
    /** File naming function */
    filename?: (file: T, req: any) => string;
    /** Get user identity */
    userIdentifier?: UserIdentifier;
    /** Force relative URI in Location header */
    useRelativeLocation?: boolean;
    /** Callback function that is called when a new upload is created */
    onCreate?: OnCreate<T>;
    /** Callback function that is called when an upload is updated */
    onUpdate?: OnUpdate<T>;
    /** Callback function that is called when an upload is completed */
    onComplete?: OnComplete<T>;
    /** Callback function that is called when an upload is cancelled */
    onDelete?: OnDelete<T>;
    /** Customize error response */
    onError?: OnError;
    /** Node http base path */
    path?: string;
    /** Upload validation options */
    validation?: Validation<T>;
    /** Limiting the size of custom metadata */
    maxMetadataSize?: number | string;
    /** Provide custom meta storage  */
    metaStorage?: MetaStorage<T>;
    /**
     * Automatic cleaning of abandoned and completed uploads
     *
     * @example
     * ```ts
     * app.use(
     *   '/upload',
     *   uploadx.upload({
     *     directory: 'upload',
     *     expiration: { maxAge: '6h', purgeInterval: '30min' },
     *     onComplete
     *   })
     * );
     * ```
     */
    expiration?: ExpirationOptions;
    /** Custom logger injection */
    logger?: Logger;
    /**
     * Set built-in logger severity level
     * @defaultValue 'none'
     */
    logLevel?: LogLevel;
}
export declare const locker: Locker;
export declare abstract class BaseStorage<TFile extends File> {
    config: BaseStorageOptions<TFile>;
    onCreate: (file: TFile) => Promise<UploadxResponse>;
    onUpdate: (file: TFile) => Promise<UploadxResponse>;
    onComplete: (file: TFile) => Promise<UploadxResponse>;
    onDelete: (file: TFile) => Promise<UploadxResponse>;
    onError: (err: HttpError) => UploadxResponse;
    maxUploadSize: number;
    maxMetadataSize: number;
    path: string;
    isReady: boolean;
    checksumTypes: string[];
    errorResponses: ErrorResponses;
    cache: Cache<TFile>;
    logger: Logger;
    protected namingFunction: (file: TFile, req: any) => string;
    protected validation: Validator<TFile>;
    abstract meta: MetaStorage<TFile>;
    protected constructor(config: BaseStorageOptions<TFile>);
    validate(file: TFile): Promise<any>;
    normalizeError(error: Error): HttpError;
    /**
     * Saves upload metadata
     */
    saveMeta(file: TFile): Promise<TFile>;
    /**
     * Deletes an upload metadata
     */
    deleteMeta(id: string): Promise<void>;
    /**
     * Retrieves upload metadata
     */
    getMeta(id: string): Promise<TFile>;
    checkIfExpired(file: TFile): Promise<TFile>;
    /**
     * Searches for and purges expired uploads
     * @param maxAge - remove uploads older than a specified age
     * @param prefix - filter uploads
     */
    purge(maxAge?: number | string, prefix?: string): Promise<PurgeList>;
    get({ id }: FilePart): Promise<UploadList>;
    /**
     * Retrieves a list of uploads whose names begin with the prefix
     * @experimental
     */
    list(prefix?: string): Promise<UploadList>;
    /**
     * Set user-provided metadata as key-value pairs
     * @experimental
     */
    update({ id }: FileQuery, metadata: Partial<File>): Promise<TFile>;
    /**
     * Prevent upload from being accessed by multiple requests
     */
    lock(key: string): Promise<string>;
    unlock(key: string): Promise<void>;
    protected isUnsupportedChecksum(algorithm?: string): boolean;
    protected startAutoPurge(purgeInterval: number): void;
    protected updateTimestamps(file: TFile): TFile;
    /**
     *  Creates a new upload and saves its metadata
     */
    abstract create(req: IncomingMessage, file: FileInit): Promise<TFile>;
    /**
     *  Write part and/or return status of an upload
     */
    abstract write(part: FilePart | FileQuery): Promise<TFile>;
    /**
     * Deletes an upload and its metadata
     */
    abstract delete(query: FileQuery): Promise<TFile[]>;
}