| 1 | /*!
|
| 2 | * Copyright 2015 Google Inc. All Rights Reserved.
|
| 3 | *
|
| 4 | * Licensed under the Apache License, Version 2.0 (the "License");
|
| 5 | * you may not use this file except in compliance with the License.
|
| 6 | * You may obtain a copy of the License at
|
| 7 | *
|
| 8 | * http://www.apache.org/licenses/LICENSE-2.0
|
| 9 | *
|
| 10 | * Unless required by applicable law or agreed to in writing, software
|
| 11 | * distributed under the License is distributed on an "AS IS" BASIS,
|
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
| 13 | * See the License for the specific language governing permissions and
|
| 14 | * limitations under the License.
|
| 15 | */
|
| 16 | /// <reference types="node" />
|
| 17 | import { TransformOptions } from 'stream';
|
| 18 | import { ResourceStream } from './resource-stream';
|
| 19 | export interface ParsedArguments extends TransformOptions {
|
| 20 | /**
|
| 21 | * Query object. This is most commonly an object, but to make the API more
|
| 22 | * simple, it can also be a string in some places.
|
| 23 | */
|
| 24 | query?: ParsedArguments;
|
| 25 | /**
|
| 26 | * Callback function.
|
| 27 | */
|
| 28 | callback?: Function;
|
| 29 | /**
|
| 30 | * Auto-pagination enabled.
|
| 31 | */
|
| 32 | autoPaginate?: boolean;
|
| 33 | /**
|
| 34 | * Maximum API calls to make.
|
| 35 | */
|
| 36 | maxApiCalls?: number;
|
| 37 | /**
|
| 38 | * Maximum results to return.
|
| 39 | */
|
| 40 | maxResults?: number;
|
| 41 | pageSize?: number;
|
| 42 | streamOptions?: ParsedArguments;
|
| 43 | }
|
| 44 | /*! Developer Documentation
|
| 45 | *
|
| 46 | * paginator is used to auto-paginate `nextQuery` methods as well as
|
| 47 | * streamifying them.
|
| 48 | *
|
| 49 | * Before:
|
| 50 | *
|
| 51 | * search.query('done=true', function(err, results, nextQuery) {
|
| 52 | * search.query(nextQuery, function(err, results, nextQuery) {});
|
| 53 | * });
|
| 54 | *
|
| 55 | * After:
|
| 56 | *
|
| 57 | * search.query('done=true', function(err, results) {});
|
| 58 | *
|
| 59 | * Methods to extend should be written to accept callbacks and return a
|
| 60 | * `nextQuery`.
|
| 61 | */
|
| 62 | export declare class Paginator {
|
| 63 | /**
|
| 64 | * Cache the original method, then overwrite it on the Class's prototype.
|
| 65 | *
|
| 66 | * @param {function} Class - The parent class of the methods to extend.
|
| 67 | * @param {string|string[]} methodNames - Name(s) of the methods to extend.
|
| 68 | */
|
| 69 | extend(Class: Function, methodNames: string | string[]): void;
|
| 70 | /**
|
| 71 | * Wraps paginated API calls in a readable object stream.
|
| 72 | *
|
| 73 | * This method simply calls the nextQuery recursively, emitting results to a
|
| 74 | * stream. The stream ends when `nextQuery` is null.
|
| 75 | *
|
| 76 | * `maxResults` will act as a cap for how many results are fetched and emitted
|
| 77 | * to the stream.
|
| 78 | *
|
| 79 | * @param {string} methodName - Name of the method to streamify.
|
| 80 | * @return {function} - Wrapped function.
|
| 81 | */
|
| 82 | streamify<T = any>(methodName: string): (this: {
|
| 83 | [index: string]: Function;
|
| 84 | }, ...args: any[]) => ResourceStream<T>;
|
| 85 | /**
|
| 86 | * Parse a pseudo-array `arguments` for a query and callback.
|
| 87 | *
|
| 88 | * @param {array} args - The original `arguments` pseduo-array that the original
|
| 89 | * method received.
|
| 90 | */
|
| 91 | parseArguments_(args: any[]): ParsedArguments;
|
| 92 | /**
|
| 93 | * This simply checks to see if `autoPaginate` is set or not, if it's true
|
| 94 | * then we buffer all results, otherwise simply call the original method.
|
| 95 | *
|
| 96 | * @param {array} parsedArguments - Parsed arguments from the original method
|
| 97 | * call.
|
| 98 | * @param {object=|string=} parsedArguments.query - Query object. This is most
|
| 99 | * commonly an object, but to make the API more simple, it can also be a
|
| 100 | * string in some places.
|
| 101 | * @param {function=} parsedArguments.callback - Callback function.
|
| 102 | * @param {boolean} parsedArguments.autoPaginate - Auto-pagination enabled.
|
| 103 | * @param {boolean} parsedArguments.maxApiCalls - Maximum API calls to make.
|
| 104 | * @param {number} parsedArguments.maxResults - Maximum results to return.
|
| 105 | * @param {function} originalMethod - The cached method that accepts a callback
|
| 106 | * and returns `nextQuery` to receive more results.
|
| 107 | */
|
| 108 | run_(parsedArguments: ParsedArguments, originalMethod: Function): any;
|
| 109 | /**
|
| 110 | * This method simply calls the nextQuery recursively, emitting results to a
|
| 111 | * stream. The stream ends when `nextQuery` is null.
|
| 112 | *
|
| 113 | * `maxResults` will act as a cap for how many results are fetched and emitted
|
| 114 | * to the stream.
|
| 115 | *
|
| 116 | * @param {object=|string=} parsedArguments.query - Query object. This is most
|
| 117 | * commonly an object, but to make the API more simple, it can also be a
|
| 118 | * string in some places.
|
| 119 | * @param {function=} parsedArguments.callback - Callback function.
|
| 120 | * @param {boolean} parsedArguments.autoPaginate - Auto-pagination enabled.
|
| 121 | * @param {boolean} parsedArguments.maxApiCalls - Maximum API calls to make.
|
| 122 | * @param {number} parsedArguments.maxResults - Maximum results to return.
|
| 123 | * @param {function} originalMethod - The cached method that accepts a callback
|
| 124 | * and returns `nextQuery` to receive more results.
|
| 125 | * @return {stream} - Readable object stream.
|
| 126 | */
|
| 127 | runAsStream_<T = any>(parsedArguments: ParsedArguments, originalMethod: Function): ResourceStream<T>;
|
| 128 | }
|
| 129 | declare const paginator: Paginator;
|
| 130 | export { paginator };
|
| 131 | export { ResourceStream };
|