@vidispine/vdt-js 23.4.0-pre.3 → 23.4.0

package/dist/index.d.ts

@@ -4,6 +4,8 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import type { AudioComponentType } from '@vidispine/types';
 import type { BinaryComponentType } from '@vidispine/types';
 import type { CollectionType } from '@vidispine/types';
@@ -30,6 +32,271 @@ import type { VideoComponentType } from '@vidispine/types';
 
 declare type ArrayElement<ArrayType> = ArrayType extends readonly (infer ElementType)[] ? ElementType : never;
 
+/**
+ * Representation of a chunk sent by `ChunkUpload`
+ *
+ * @category Upload
+ */
+export declare class Chunk {
+    state: ChunkState;
+    eventBus: ChunkedUploadEventBus;
+    tryTimeout: NodeJS.Timeout;
+    transferPromise: any;
+    start: number;
+    end: number;
+    fileSize: number;
+    blobSlice: any;
+    api: {
+        method?: (options: {
+            file: any;
+            onUploadProgress: (progressEvent: {
+                loaded: number;
+            }) => void;
+            headers?: {
+                index: number;
+                size: number;
+            };
+        }) => any;
+        props?: any;
+    };
+    constructor(props?: ChunkProps);
+    /**
+     * Attempt to transfer chunk with some fault resilience.
+     *
+     * - 3 retires with 1 second apart in case of failure
+     * - Pauses/resumes chunk transfer when network is offline/online
+     *
+     * @returns Promise of the transfer request
+     */
+    tryTransfer(): Promise<Chunk>;
+    /**
+     * Transfers `blobSlice` on this object with the `api.method`
+     *
+     * Triggers: `EVENTS.progress`
+     * Status: `STATUSES.transferring`
+     *
+     * @returns Promise for the transfer
+     */
+    transfer(): any;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+    get transferRate(): number;
+    private onComplete;
+}
+
+/**
+ * Class for sending and controlling multiple `ChunkedUpload` objects
+ *
+ * @category Upload
+ */
+export declare class ChunkedTransferManager {
+    initialState: ChunkedTransferManagerState;
+    state: ChunkedTransferManagerState;
+    options: ChunkedTransferManagerOptions;
+    events: ChunkedUploadEventBus;
+    constructor(options?: ChunkedTransferManagerOptions);
+    get transfers(): ChunkedUpload[];
+    get status(): number;
+    set status(value: number);
+    get bytesTotal(): number;
+    get bytesDone(): number;
+    get isUploading(): boolean;
+    get paused(): boolean;
+    bindNetworkEvents(): void;
+    addChunkedUpload(chunkedUpload: ChunkedUpload): void;
+    removeChunkedUpload(InstanceOrFileOrTransferId: ChunkedUpload | File | string, force?: boolean): void;
+    onProgress(): void;
+    onComplete(): void;
+    exists(file: File): ChunkedUpload;
+    isTransferAvailable(transfer: any): boolean;
+    pause(): Promise<any>;
+    resume(): void;
+    retry(): void;
+    upload(): void;
+    onFail(error: any, state: ChunkedUpload['state']): void;
+    reset(): void;
+    destroy(): void;
+    get hasCompleted(): boolean;
+    updateStats(): void;
+    get percentDone(): number;
+    get fileList(): any[];
+}
+
+export declare type ChunkedTransferManagerOptions = {
+    maxConcurrentFileTransfers: number;
+    autoResume: boolean;
+};
+
+export declare type ChunkedTransferManagerState = {
+    status: number;
+    transfers: ChunkedUpload[];
+    bytesDone: number;
+    bytesTotal: number;
+    lastStats: {
+        bytesDone: number;
+        bytesTotal: number;
+    };
+};
+
+/**
+ * Class for dividing blobs/files into chunks and sending them through the supplied `options.api.method`
+ *
+ * @category Upload
+ */
+export declare class ChunkedUpload {
+    readonly DEFAULT_OPTIONS: ChunkedUploadOptions;
+    eventBus: ChunkedUploadEventBus;
+    options: ChunkedUploadOptions;
+    state: ChunkedUploadState;
+    constructor(file: File, options: ChunkedUploadOptions);
+    upload(): void;
+    getByteRangesForChunks(blob: Blob, chunkSize?: number): any[];
+    addChunksFromBlob(blob: Blob): void;
+    retry(): void;
+    resume(): void;
+    pause(): Promise<Chunk[]>;
+    cancel(): Promise<Chunk[]>;
+    autoAdjustMaxConcurrentTransfers(stats: any): void;
+    onProgress(): void;
+    onComplete(): void;
+    getStats(): {
+        totalChunks: number;
+        completedChunks: number;
+        totalBytes: number;
+        transferredBytes: number;
+        avgTransferRate: number;
+        concurrentTransfers: number;
+    };
+    set concurrentTransfers(int: any);
+    set rate(int: number);
+    get rate(): number;
+    get finalResponse(): false | object;
+    get transferId(): string;
+}
+
+/**
+ * Event bus used by `Chunk`, `ChunkedUpload` and `ChunkedTransferManager` to communicate
+ *
+ * @category Upload
+ */
+export declare class ChunkedUploadEventBus {
+    events: ChunkedUploadEventBusEvents;
+    constructor();
+    /**
+     * Add a callback for a specific event type
+     *
+     * @param event event type
+     * @param callback function receiving state of chunk, transfer manager or chunked upload instance
+     */
+    on(event: EVENTS, callback: (data: Chunk['state'] | ChunkedTransferManager['state'] | ChunkedUpload['state'], error?: any) => void): void;
+    /**
+     * Remove all callbacks for a specific event type
+     *
+     * @param event event type
+     */
+    off(event: EVENTS): void;
+    /**
+     * Trigger callbacks for a specific event
+     *
+     * @param event
+     * @param data
+     * @returns
+     */
+    trigger(event: EVENTS, data: Chunk['state'] | ChunkedTransferManager['state'] | ChunkedUpload['state'], error?: any): void;
+}
+
+export declare type ChunkedUploadEventBusEvents = {
+    [key in EVENTS]?: Array<(data: Chunk['state'] | ChunkedTransferManager['state'] | ChunkedUpload['state'], error?: any) => void>;
+};
+
+export declare type ChunkedUploadOptions = {
+    targetRate?: number;
+    chunkSize?: number;
+    minChunkSize?: number;
+    maxConcurrentTransfers?: number;
+    maxConcurrentFileTransfers?: number;
+    autoMaxConcurrentTransfers?: boolean;
+    minFileSize?: number;
+    api?: {
+        props?: {
+            pathParams?: {
+                [key: string]: any;
+            };
+            queryParams?: {
+                transferId?: string;
+                [key: string]: any;
+            };
+            data?: any;
+        };
+        method?: any;
+        [key: string]: any;
+    };
+    /**
+     * ChunkedTransferManager -> automatically resume transfers when network connection become active
+     */
+    autoResume?: boolean;
+    onComplete?: (finalResponse?: false | object) => void;
+    onProgress?: (stats?: ChunkedUploadStats) => void;
+    onFail?: (error?: any) => void;
+};
+
+export declare type ChunkedUploadState = {
+    blob: {
+        name: string;
+        lastModified: number;
+        size: number;
+    };
+    chunks: Chunk[];
+    status: number;
+    transferPromises: Promise<Chunk>[];
+    targetRate: number;
+    rate: number;
+    autoMaxConcurrentTransfers: boolean;
+    maxConcurrentTransfers: number;
+    mime: string;
+    transferId: string;
+    lastStats: {};
+};
+
+export declare type ChunkedUploadStats = {
+    totalChunks?: number;
+    completedChunks?: number;
+    totalBytes?: number;
+    transferredBytes?: number;
+    avgTransferRate?: number;
+    concurrentTransfers?: number;
+};
+
+export declare type ChunkProps = {
+    start?: number;
+    end?: number;
+    fileSize?: number;
+    blobSlice?: any;
+    api?: {
+        method?: (options?: {
+            file?: any;
+            onUploadProgress?: (progressEvent: {
+                loaded: number;
+            }) => void;
+            headers?: {
+                index: number;
+                size: number;
+            };
+        }) => any;
+        props?: any;
+    };
+};
+
+export declare type ChunkState = {
+    retries: number;
+    status: number;
+    startTime: number | null;
+    completeTime: number | null;
+    response: any;
+    bytesTransferred: number | null;
+};
+
 /**
  * Create a VidiCore metadata object from a more dense/simplified structure
  *
@@ -83,8 +350,6 @@ export declare const createTimeCode: (timeCode: TimeCodeInput | string | number,
 
 export declare type CreateTimeCodeOptions = TimeCodeInputOptions | FormatTimeCodeSmpteOptions | FormatTimeCodeSecondsOptions | FormatTimeCodeTextOptions;
 
-export declare const defaultOptions: ParseSearchResultEventsOptions;
-
 /**
  * Const object with document types
  *
@@ -101,6 +366,27 @@ export declare const DOCUMENT_TYPES: {
 declare type DocumentType_2 = keyof typeof DOCUMENT_TYPES;
 export { DocumentType_2 as DocumentType }
 
+/**
+ * Chunked upload event types
+ *
+ * @category Upload
+ */
+export declare enum EVENTS {
+    progress = "progress",
+    update = "update",
+    complete = "complete",
+    error = "error",
+    added = "upload-added",
+    removed = "upload-removed",
+    failed = "upload-failed",
+    retry = "retry",
+    pausing = "pausing",
+    paused = "paused",
+    resuming = "resuming",
+    offline = "offline",
+    online = "online"
+}
+
 /**
  * Array with all available metadata field attributes
  *
@@ -156,8 +442,38 @@ export declare const FILE_STATES: {
     readonly AWAITING_SYNC: "AWAITING_SYNC";
 };
 
+export declare type FileLike = Partial<File> & {
+    path?: string;
+};
+
+/**
+ * Converts a list of files into a tree structure
+ *
+ * Works with `path` or the native `webkitRelativePath`
+ *
+ * @param files An array of file like objects
+ * @returns A file tree object
+ *
+ * @category Upload
+ */
+export declare const fileListToFileTree: (files: FileLike[]) => {
+    [key: string]: FileTree;
+};
+
 export declare type FileStateTypes = keyof typeof FILE_STATES;
 
+export declare type FileTree = {
+    file: File;
+    path?: string;
+    progress?: {
+        totalBytes: number;
+        transferredBytes: number;
+    };
+    files?: {
+        [fileName: string]: FileTree;
+    };
+};
+
 export declare type FilteredShapeListObject = {
     src: string;
     type: string;
@@ -662,7 +978,7 @@ export declare type ParsedMetadataType<TOptions> = (TOptions extends {
     includeMetadataAttributes?: true | string[];
 } ? ParsedMetadataAttributes : {});
 
-export declare type ParsedSearchResultEntryTimespanType = {
+declare type ParsedSearchResultEntryTimespanType = {
     entityType?: 'Item' | 'Collection';
     entityId?: string;
     group?: MetadataGroupValueType;
@@ -673,7 +989,7 @@ export declare type ParsedSearchResultEntryTimespanType = {
     endSeconds?: number;
 };
 
-export declare type ParsedSearchResultEntryType = {
+declare type ParsedSearchResultEntryType = {
     entityType: 'Item' | 'Collection';
     entityId: string;
     events?: ParsedSearchResultEntryTimespanType[];
@@ -681,7 +997,7 @@ export declare type ParsedSearchResultEntryType = {
     collectionType?: CollectionType;
 };
 
-export declare type ParsedSearchResultEvents<TOptions> = TOptions extends {
+declare type ParsedSearchResultEvents<TOptions> = TOptions extends {
     flatEvents?: true;
 } ? ParsedSearchResultEntryTimespanType[] : ParsedSearchResultEntryType[];
 
@@ -1002,13 +1318,15 @@ export declare const parseNowDate: (value?: string) => Date;
  * - https://apidoc.vidispine.com/latest/ref/search.html#search-collection-and-item-by-metadata-group
  * - https://apidoc.vidispine.com/latest/item/search.html#find-item-and-collections-by-their-metadata-groups
  *
- * @param searchResult
- * @param options
- * @returns
+ * @param searchResult Metadata-group search results that should be parsed into events
+ * @param options options for tweaking how search results should be parsed
+ * @returns Search results converted to an array of more event-like objects
+ *
+ * @category Search
  */
 export declare const parseSearchResultEvents: <TOptions extends ParseSearchResultEventsOptions = ParseSearchResultEventsOptions>(searchResult?: SearchResultType, options?: TOptions) => ParsedSearchResultEvents<TOptions>;
 
-export declare type ParseSearchResultEventsOptions = {
+declare type ParseSearchResultEventsOptions = {
     /**
      * Append matching group with metadata
      */
@@ -1296,6 +1614,21 @@ export declare const SHAPE_MEDIA_TYPES: {
 
 export declare type ShapeMediaType = keyof typeof SHAPE_MEDIA_TYPES;
 
+/**
+ * Chunked upload status types
+ *
+ * @category Upload
+ */
+export declare enum STATUSES {
+    transferring = 1,
+    paused = 2,
+    complete = 3,
+    failed = 4,
+    idle = 5,
+    canceled = 6,
+    offline = 7
+}
+
 /**
  * Array with all available VidiCore system/default field group names
  *
@@ -1540,9 +1873,11 @@ export declare class TimeCode {
     /**
      * Get TimeCode in a smpte representation
      *
+     * @param {Object} options
+     * @param {boolean} options.uniformSeparators Use the frame separator for all separators in the smpte string
      * @returns Smpte representation of the TimeCode
      */
-    toSmpte(): string;
+    toSmpte(options?: ToSmpteOptions): string;
     /**
      * Get TimeCode as a VidiCore TimeCodeType object
      *
@@ -1594,4 +1929,8 @@ declare type TimeCodeToSecondsOptions = {
     round?: boolean;
 };
 
+export declare type ToSmpteOptions = {
+    uniformSeparators?: boolean;
+};
+
 export { }