@jsforce/jsforce-node 0.0.1 → 3.0.0-next.1

package/lib/api/bulk.d.ts

@@ -0,0 +1,444 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * @file Manages Salesforce Bulk API related operations
+ * @author Shinichi Tomita <shinichi.tomita@gmail.com>
+ */
+import { EventEmitter } from 'events';
+import { Duplex, Readable, Writable } from 'stream';
+import Connection from '../connection';
+import { Serializable, Parsable } from '../record-stream';
+import { StreamPromise } from '../util/promise';
+import { Logger } from '../util/logger';
+import { HttpMethods, Record, Schema, Optional } from '../types';
+export type BulkOperation = 'insert' | 'update' | 'upsert' | 'delete' | 'hardDelete' | 'query' | 'queryAll';
+export type IngestOperation = Exclude<BulkOperation, 'query' | 'queryAll'>;
+export type QueryOperation = Extract<BulkOperation, 'query' | 'queryAll'>;
+export type BulkOptions = {
+    extIdField?: string;
+    concurrencyMode?: 'Serial' | 'Parallel';
+    assignmentRuleId?: string;
+};
+export type JobState = 'Open' | 'Closed' | 'Aborted' | 'Failed' | 'Unknown';
+export type JobStateV2 = Exclude<JobState, 'Closed' | 'Unknown'> | 'UploadComplete' | 'InProgress' | 'JobComplete';
+export type JobInfo = {
+    id: string;
+    object: string;
+    operation: BulkOperation;
+    state: JobState;
+};
+export type JobInfoV2 = {
+    apiVersion: string;
+    assignmentRuleId?: string;
+    columnDelimiter: 'BACKQUOTE' | 'CARET' | 'COMMA' | 'PIPE' | 'SEMICOLON' | 'TAB';
+    concurrencyMode: 'Parallel';
+    contentType: 'CSV';
+    contentUrl: string;
+    createdById: string;
+    createdDate: string;
+    externalIdFieldName?: string;
+    id: string;
+    jobType: 'BigObjectIngest' | 'Classic' | 'V2Ingest';
+    lineEnding: 'LF' | 'CRLF';
+    object: string;
+    operation: BulkOperation;
+    state: JobStateV2;
+    systemModstamp: string;
+    numberRecordsProcessed?: number;
+    numberRecordsFailed?: number;
+};
+export type BatchState = 'Queued' | 'InProgress' | 'Completed' | 'Failed' | 'NotProcessed';
+export type BatchInfo = {
+    id: string;
+    jobId: string;
+    state: BatchState;
+    stateMessage: string;
+    numberRecordsProcessed: string;
+    numberRecordsFailed: string;
+    totalProcessingTime: string;
+};
+export type BulkQueryBatchResult = Array<{
+    id: string;
+    batchId: string;
+    jobId: string;
+}>;
+export type BulkIngestBatchResult = Array<{
+    id: string | null;
+    success: boolean;
+    errors: string[];
+}>;
+export type BatchResult<Opr extends BulkOperation> = Opr extends 'query' | 'queryAll' ? BulkQueryBatchResult : BulkIngestBatchResult;
+type BulkRequest = {
+    method: HttpMethods;
+    path: string;
+    body?: string;
+    headers?: {
+        [name: string]: string;
+    };
+    responseType?: string;
+};
+export type IngestJobV2SuccessfulResults<S extends Schema> = Array<{
+    sf__Created: 'true' | 'false';
+    sf__Id: string;
+} & S>;
+export type IngestJobV2FailedResults<S extends Schema> = Array<{
+    sf__Error: string;
+    sf__Id: string;
+} & S>;
+export type IngestJobV2UnprocessedRecords<S extends Schema> = Array<S>;
+export type IngestJobV2Results<S extends Schema> = {
+    successfulResults: IngestJobV2SuccessfulResults<S>;
+    failedResults: IngestJobV2FailedResults<S>;
+    unprocessedRecords: IngestJobV2UnprocessedRecords<S>;
+};
+type NewIngestJobOptions = Required<Pick<JobInfoV2, 'object' | 'operation'>> & Partial<Pick<JobInfoV2, 'assignmentRuleId' | 'externalIdFieldName' | 'lineEnding'>>;
+type ExistingIngestJobOptions = Pick<JobInfoV2, 'id'>;
+type CreateIngestJobV2Options<S extends Schema> = {
+    connection: Connection<S>;
+    jobInfo: NewIngestJobOptions | ExistingIngestJobOptions;
+    pollingOptions: BulkV2PollingOptions;
+};
+type CreateQueryJobV2Options<S extends Schema> = {
+    connection: Connection<S>;
+    operation: QueryOperation;
+    query: string;
+    pollingOptions: BulkV2PollingOptions;
+};
+type BulkV2PollingOptions = {
+    pollInterval: number;
+    pollTimeout: number;
+};
+/**
+ * Class for Bulk API Job
+ */
+export declare class Job<S extends Schema, Opr extends BulkOperation> extends EventEmitter {
+    type: string | null;
+    operation: Opr | null;
+    options: BulkOptions;
+    id: string | null;
+    state: JobState;
+    _bulk: Bulk<S>;
+    _batches: {
+        [id: string]: Batch<S, Opr>;
+    };
+    _jobInfo: Promise<JobInfo> | undefined;
+    _error: Error | undefined;
+    /**
+     *
+     */
+    constructor(bulk: Bulk<S>, type: string | null, operation: Opr | null, options: BulkOptions | null, jobId?: string);
+    /**
+     * Return latest jobInfo from cache
+     */
+    info(): Promise<JobInfo>;
+    /**
+     * Open new job and get jobinfo
+     */
+    open(): Promise<JobInfo>;
+    /**
+     * Create a new batch instance in the job
+     */
+    createBatch(): Batch<S, Opr>;
+    /**
+     * Get a batch instance specified by given batch ID
+     */
+    batch(batchId: string): Batch<S, Opr>;
+    /**
+     * Check the latest job status from server
+     */
+    check(): Promise<JobInfo>;
+    /**
+     * Wait till the job is assigned to server
+     */
+    ready(): Promise<string>;
+    /**
+     * List all registered batch info in job
+     */
+    list(): Promise<BatchInfo[]>;
+    /**
+     * Close opened job
+     */
+    close(): Promise<JobInfo | undefined>;
+    /**
+     * Set the status to abort
+     */
+    abort(): Promise<JobInfo | undefined>;
+    /**
+     * @private
+     */
+    _changeState(state: JobState): Promise<JobInfo>;
+}
+/**
+ * Batch (extends Writable)
+ */
+export declare class Batch<S extends Schema, Opr extends BulkOperation> extends Writable {
+    job: Job<S, Opr>;
+    id: string | undefined;
+    _bulk: Bulk<S>;
+    _uploadStream: Serializable;
+    _downloadStream: Parsable;
+    _dataStream: Duplex;
+    _result: Promise<BatchResult<Opr>> | undefined;
+    _error: Error | undefined;
+    /**
+     *
+     */
+    constructor(job: Job<S, Opr>, id?: string);
+    /**
+     * Connect batch API and create stream instance of request/response
+     *
+     * @private
+     */
+    _createRequestStream(): Duplex;
+    /**
+     * Implementation of Writable
+     */
+    _write(record_: Record, enc: BufferEncoding, cb: () => void): void;
+    /**
+     * Returns duplex stream which accepts CSV data input and batch result output
+     */
+    stream(): Duplex;
+    /**
+     * Execute batch operation
+     */
+    execute(input?: string | Record[] | Readable): this;
+    run: (input?: string | Record[] | Readable) => this;
+    exec: (input?: string | Record[] | Readable) => this;
+    /**
+     * Promise/A+ interface
+     * Delegate to promise, return promise instance for batch result
+     */
+    then(onResolved: (res: BatchResult<Opr>) => void, onReject: (err: any) => void): Promise<void>;
+    /**
+     * Check the latest batch status in server
+     */
+    check(): Promise<BatchInfo>;
+    /**
+     * Polling the batch result and retrieve
+     */
+    poll(interval: number, timeout: number): void;
+    /**
+     * Retrieve batch result
+     */
+    retrieve(): Promise<BulkQueryBatchResult | BulkIngestBatchResult>;
+    /**
+     * Fetch query result as a record stream
+     * @param {String} resultId - Result id
+     * @returns {RecordStream} - Record stream, convertible to CSV data stream
+     */
+    result(resultId: string): Parsable<Record>;
+}
+/**
+ * Class for Bulk API
+ *
+ * @class
+ */
+export declare class Bulk<S extends Schema> {
+    _conn: Connection<S>;
+    _logger: Logger;
+    /**
+     * Polling interval in milliseconds
+     */
+    pollInterval: number;
+    /**
+     * Polling timeout in milliseconds
+     * @type {Number}
+     */
+    pollTimeout: number;
+    /**
+     *
+     */
+    constructor(conn: Connection<S>);
+    /**
+     *
+     */
+    _request<T>(request_: BulkRequest): StreamPromise<T>;
+    /**
+     * Create and start bulkload job and batch
+     */
+    load<Opr extends BulkOperation>(type: string, operation: Opr, input?: Record[] | Readable | string): Batch<S, Opr>;
+    load<Opr extends BulkOperation>(type: string, operation: Opr, optionsOrInput?: BulkOptions | Record[] | Readable | string, input?: Record[] | Readable | string): Batch<S, Opr>;
+    /**
+     * Execute bulk query and get record stream
+     */
+    query(soql: string): Parsable<Record>;
+    /**
+     * Create a new job instance
+     */
+    createJob<Opr extends BulkOperation>(type: string, operation: Opr, options?: BulkOptions): Job<S, Opr>;
+    /**
+     * Get a job instance specified by given job ID
+     *
+     * @param {String} jobId - Job ID
+     * @returns {Bulk~Job}
+     */
+    job<Opr extends BulkOperation>(jobId: string): Job<S, Opr>;
+}
+export declare class BulkV2<S extends Schema> {
+    #private;
+    /**
+     * Polling interval in milliseconds
+     */
+    pollInterval: number;
+    /**
+     * Polling timeout in milliseconds
+     * @type {Number}
+     */
+    pollTimeout: number;
+    constructor(connection: Connection<S>);
+    /**
+     * Create an instance of an ingest job object.
+     *
+     * @params {NewIngestJobOptions} options object
+     * @returns {IngestJobV2} An ingest job instance
+     * @example
+     * // Upsert records to the Account object.
+     *
+     * const job = connection.bulk2.createJob({
+     *   operation: 'insert'
+     *   object: 'Account',
+     * });
+     *
+     * // create the job in the org
+     * await job.open()
+     *
+     * // upload data
+     * await job.uploadData(csvFile)
+     *
+     * // finished uploading data, mark it as ready for processing
+     * await job.close()
+     */
+    createJob<Opr extends IngestOperation>(options: NewIngestJobOptions): IngestJobV2<S, Opr>;
+    /**
+     * Get a ingest job instance specified by a given job ID
+     *
+     * @param options Options object with a job ID
+     * @returns IngestJobV2 An ingest job
+     */
+    job<Opr extends IngestOperation>(options: ExistingIngestJobOptions): IngestJobV2<S, Opr>;
+    /**
+     * Create, upload, and start bulkload job
+     */
+    loadAndWaitForResults(options: NewIngestJobOptions & Partial<BulkV2PollingOptions> & {
+        input: Record[] | Readable | string;
+    }): Promise<IngestJobV2Results<S>>;
+    /**
+     * Execute bulk query and get records
+     *
+     * Default timeout: 10000ms
+     *
+     * @param soql SOQL query
+     * @param BulkV2PollingOptions options object
+     *
+     * @returns Record[]
+     */
+    query(soql: string, options?: Partial<BulkV2PollingOptions> & {
+        scanAll?: boolean;
+    }): Promise<Record[]>;
+}
+export declare class QueryJobV2<S extends Schema> extends EventEmitter {
+    #private;
+    jobInfo: Partial<JobInfoV2> | undefined;
+    locator: Optional<string>;
+    finished: boolean;
+    constructor(options: CreateQueryJobV2Options<S>);
+    /**
+     * Creates a query job
+     */
+    open(): Promise<void>;
+    /**
+     * Set the status to abort
+     */
+    abort(): Promise<void>;
+    /**
+     * Poll for the state of the processing for the job.
+     *
+     * This method will only throw after a timeout. To capture a
+     * job failure while polling you must set a listener for the
+     * `failed` event before calling it:
+     *
+     * job.on('failed', (err) => console.error(err))
+     * await job.poll()
+     *
+     * @param interval Polling interval in milliseconds
+     * @param timeout Polling timeout in milliseconds
+     * @returns {Promise<Record[]>} A promise that resolves to an array of records
+     */
+    poll(interval?: number, timeout?: number): Promise<void>;
+    /**
+     * Check the latest batch status in server
+     */
+    check(): Promise<JobInfoV2>;
+    private request;
+    private getResultsUrl;
+    /**
+     * Get the results for a query job.
+     *
+     * @returns {Promise<Record[]>} A promise that resolves to an array of records
+     */
+    getResults(): Promise<Record[]>;
+    /**
+     * Deletes a query job.
+     */
+    delete(): Promise<void>;
+    private createQueryRequest;
+}
+/**
+ * Class for Bulk API V2 Ingest Job
+ */
+export declare class IngestJobV2<S extends Schema, Opr extends IngestOperation> extends EventEmitter {
+    #private;
+    jobInfo: Partial<JobInfoV2>;
+    /**
+     *
+     */
+    constructor(options: CreateIngestJobV2Options<S>);
+    get id(): string | undefined;
+    /**
+     * Create a job representing a bulk operation in the org
+     */
+    open(): Promise<void>;
+    /** Upload data for a job in CSV format
+     *
+     *  @param input CSV as a string, or array of records or readable stream
+     */
+    uploadData(input: string | Record[] | Readable): Promise<void>;
+    getAllResults(): Promise<IngestJobV2Results<S>>;
+    /**
+     * Close opened job
+     */
+    close(): Promise<void>;
+    /**
+     * Set the status to abort
+     */
+    abort(): Promise<void>;
+    /**
+     * Poll for the state of the processing for the job.
+     *
+     * This method will only throw after a timeout. To capture a
+     * job failure while polling you must set a listener for the
+     * `failed` event before calling it:
+     *
+     * job.on('failed', (err) => console.error(err))
+     * await job.poll()
+     *
+     * @param interval Polling interval in milliseconds
+     * @param timeout Polling timeout in milliseconds
+     * @returns {Promise<void>} A promise that resolves when the job finishes successfully
+     */
+    poll(interval?: number, timeout?: number): Promise<void>;
+    /**
+     * Check the latest batch status in server
+     */
+    check(): Promise<JobInfoV2>;
+    getSuccessfulResults(): Promise<IngestJobV2SuccessfulResults<S>>;
+    getFailedResults(): Promise<IngestJobV2FailedResults<S>>;
+    getUnprocessedRecords(): Promise<IngestJobV2UnprocessedRecords<S>>;
+    /**
+     * Deletes an ingest job.
+     */
+    delete(): Promise<void>;
+    private createIngestRequest;
+}
+export default Bulk;