@graphistry/js-upload-api
Version:
Graphistry upload client for reuse by node and browser clients
228 lines • 7.76 kB
TypeScript
import { ClientType } from './types.js';
/**
* @internal
*
* <br>
*
* ## FileType
*
* Enumeration used by {@link File} subclasses {@link EdgeFile} and {@link NodeFile} to specify whether the file is a node or edge file.
*
* Primarily useful for TypeScript and runtime checks to avoid mixups when passing {@link File} objects to {@link Dataset}
*
*/
export declare enum FileType {
Node = 0,
Edge = 1
}
/**
* # File examples
*
* {@link File} objects are used for uploading data and then reusing as part of {@link Dataset} graph visualizations
*
* Powerfully, the same file may be reused in multiple {@link Dataset}s, so many variants can be made cheaply and quickly.
*
* For configuring supported file formats, see https://hub.graphistry.com/docs/api/2/rest/files/ .
*
* <br>
*
* ---
*
* <br>
*
* @example **Upload an {@link EdgeFile} from a JSON object in a columnar form**
* ```javascript
* import { EdgeFile } from '@graphistry/node-api';
* const edgesFile = new EdgeFile(
* {
* 's': ['a', 'b', 'c'],
* 'd': ['d', 'e', 'f'],
* 'v': ['v1', 'v2', 'v3']
* }
* );
* await edgesFile.upload(client);
* console.log(`EdgeFile uploaded as ID ${edgesFile.fileID}`);
* ```
*
* <br>
*
* @example **Upload an {@link EdgeFile} from a JSON object in a row-oriented form**
* ```javascript
* import { EdgeFile } from '@graphistry/node-api';
* const edgesFile = new EdgeFile(
* [
* {'s': 'a', 'd': 'd', 'v': 'v1'},
* {'s': 'b', 'd': 'e', 'v': 'v2'},
* {'s': 'c', 'd': 'f', 'v': 'v3'}
* ],
* 'json',
* 'my nodes file',
*
* // JSON parsing options:
* // - https://hub.graphistry.com/docs/api/2/rest/upload/data/#uploadjson2
* // - https://pandas.pydata.org/docs/reference/api/pandas.read_json.html
* //
* // Also: file_compression, sql_transforms, ...
* // https://hub.graphistry.com/docs/api/2/rest/files/
* {parser_options: {orient: 'records'}}
*
* );
* await edgesFile.upload(client);
* console.log(`EdgeFile uploaded as ID ${edgesFile.fileID}`);
* ```
*
* <br>
*
* @example **Upload an {@link EdgeFile} using promises**
* ```javascript
* import { EdgeFile } from '@graphistry/node-api';
* const edgesFile = new EdgeFile({'s': ['a', 'b', 'c'], 'd': ['d', 'e', 'f'], 'v': ['v1', 'v2', 'v3']});
* edgesFile.upload(client).then(
* () => console.log(`EdgeFile uploaded as ID ${edgesFile.fileID}`)
* ).catch(err => console.error('oops', err));
* ```
*
* <br>
*
* @example **Upload a {@link NodeFile} from a JSON object**
* ```javascript
* import { NodeFile } from '@graphistry/node-api';
* const nodesFile = new NodeFile({'n': ['a', 'b', 'c']});
* await nodesFile.upload(client);
* console.log(`NodeFile uploaded as ID ${nodesFile.fileID}`);
* ```
*
* <br>
*
* @example **Upload a {@link NodeFile} from an Apache Arrow Table**
* ```javascript
* import { tableFromArrays, tableToIPC } from 'apache-arrow';
* import { NodeFile } from '@graphistry/node-api';
* const json = {'n': ['a', 'b', 'c']};
* const arr = tableFromArrays(json);
* const uint8Buf = tableToIPC(arr);
* const nodesFile = new NodeFile(uint8Buf, 'arrow');
* await nodesFile.upload(client);
* console.log(`NodeFile uploaded as ID ${nodesFile.fileID}`);
* ```
*
* <br>
*
* @example **Create a {@link File} by ID (e.g., previously uploaded) for use with {@link Dataset}s**
* ```javascript
* import { EdgeFile, Dataset } from '@graphistry/node-api';
* const edgesFile = new EdgeFile('my_file_id');
* await (new Dataset(bindings, edgesFile)).upload(client);
* console.log(`Dataset uploaded as ID ${dataset.datasetID}`);
* ```
*/
export declare class File {
private _data;
get data(): any | undefined;
private _fileID?;
get fileID(): string | undefined;
private _fileCreated;
get fileCreated(): boolean;
private _fileCreateResponse;
get fileCreateResponse(): any;
private _fileUploaded;
get fileUploaded(): any;
private _fileValidated;
get fileValidated(): any;
private _fileUploadResponse;
get fileUploadResponse(): any;
readonly createOpts: Record<string, any>;
readonly uploadUrlOpts: string;
readonly fileFormat: string;
readonly name: string;
readonly type: FileType;
/**
*
* See examples at top of file
*
* Create a new {@link File} object for uploading or use with {@link Dataset}
*
* For more information on the available options, see:
* * Creation step metadata options: https://hub.graphistry.com/docs/api/2/rest/files/
* * Upload step options: https://hub.graphistry.com/docs/api/2/rest/files/#uploadfiledata
*
* @param type FileType.Node or FileType.Edge
* @param data Payload to pass to node-fetch. Use TypedArrays such as Uint8Array for binary data such as arrow
* @param fileFormat File format to use, e.g. 'json', 'csv', 'arrow', 'parquet', 'orc', 'xls'
* @param name Name of the file to use, e.g. 'my-file'
* @param createOpts JSON post body options to use in createFile()
* @param uploadUrlOpts URL options to use in uploadData()
*/
constructor(type: FileType, data?: any, fileFormat?: string, name?: string, createOpts?: {}, uploadUrlOpts?: string);
/**
*
* See examples at top of file
*
* Upload curent {@link File} object to the server
*
* By default, this will skip reuploading files that have already been uploaded.
*
* @param client {@link Client} object to use for uploading
* @param force If true, will force upload even if file has already been uploaded
* @returns Promise that resolves to the uploaded File object when it completes uploading
*/
upload(client: ClientType, force?: boolean): Promise<File>;
/**
*
* See examples at top of file
*
* Helper function to create the file on the server but not yet upload its data
*
* By default, this will skip recreating files that have already been created.
*
* @param client {@link Client} object to use for uploading
* @param force If true, will force creation of a new ID even if file has already been uploaded
* @returns
*/
createFile(client: ClientType, force?: boolean): Promise<any | boolean>;
/**
*
* See examples at top of file
*
* Helper function to upload the data to the server
*
* By default, this will skip reuploading data that has already been uploaded.
*
* @param client {@link Client} object to use for uploading
* @param force If true, will force upload even if file has already been uploaded
* @returns
*/
uploadData(client: ClientType, force?: boolean): Promise<any | boolean>;
/**
*
* See examples at top of file
*
* Populate data for later uploading if it wasn't set during construction
*
* Cannot run this function if the file has already been uploaded
*
* Overwrites any existing data
*
* @param data Data to use for uploading
*/
setData(data: any): void;
private fillMetadata;
}
/**
* Helper class for tracking intent when creating a {@link File} object for uploading
*
* See examples at top of file
*
*/
export declare class EdgeFile extends File {
constructor(data?: any, fileFormat?: string, name?: string, createOpts?: {}, urlOpts?: string);
}
/**
* Helper class for tracking intent when creating a {@link File} object for uploading
*
* See examples at top of file
*/
export declare class NodeFile extends File {
constructor(data?: any, fileFormat?: string, name?: string, createOpts?: {}, urlOpts?: string);
}
//# sourceMappingURL=File.d.ts.map