From 0ae13c0b44ddf0576cc6b4542277808549fa2f50 Mon Sep 17 00:00:00 2001 From: Jonathan Lui Date: Tue, 11 Sep 2018 15:45:42 -0700 Subject: [PATCH 1/3] ts: convert jsdoc types to typescript interfaces (1) --- src/bucket.ts | 153 ++++++++++++++++++++++++++++++++++---------------- src/file.ts | 2 +- 2 files changed, 107 insertions(+), 48 deletions(-) diff --git a/src/bucket.ts b/src/bucket.ts index 75addd24c..92d8c9ca2 100644 --- a/src/bucket.ts +++ b/src/bucket.ts @@ -30,6 +30,7 @@ import * as snakeize from 'snakeize'; import * as request from 'request'; import {Acl} from './acl'; +import {Channel} from './channel'; import {File, FileOptions} from './file'; import {Iam} from './iam'; import {Notification} from './notification'; @@ -49,6 +50,23 @@ interface MetadataRequest { userProject?: string; } +interface BucketOptions { + userProject?: string; +} +/** + * See a [Objects: + * watchAll request body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). + */ +interface WatchAllRequest { + delimiter: string; + maxResults: number; + pageToken: string; + prefix: string; + projection: string; + userProject: string; + versions: boolean; +} + /** * Query object for listing files. * @@ -90,6 +108,77 @@ export interface DeleteFilesRequest extends GetFilesRequest { force?: boolean; } +/** + * @typedef {object} CombineOptions + * @property {string} [kmsKeyName] Resource name of the Cloud KMS key, of + * the form + * `projects/my-project/locations/location/keyRings/my-kr/cryptoKeys/my-key`, + * that will be used to encrypt the object. Overwrites the object + * metadata's `kms_key_name` value, if any. + * @property {string} [userProject] The ID of the project which will be + * billed for the request. + */ +export interface CombineOptions { + kmsKeyName?: string; + userProject?: string; +} + +/** + * @callback CombineCallback + * @param {?Error} err Request error, if any. + * @param {File} newFile The new {@link File}. + * @param {object} apiResponse The full API response. + */ +export interface CombineCallback { + (err: Error|null, newFile: File|null, apiResponse: object); +} + +/** + * @typedef {array} CombineResponse + * @property {File} 0 The new {@link File}. + * @property {object} 1 The full API response. + */ +export type CombineResponse = [File, object]; + +/** + * See a [Objects: + * watchAll request body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). + * + * @typedef {object} CreateChannelConfig + * @property {string} address The address where notifications are + * delivered for this channel. + */ +export interface CreateChannelConfig extends WatchAllRequest { + address: string; +} + +/** + * @typedef {object} CreateChannelOptions + * @property {string} [userProject] The ID of the project which will be + * billed for the request. + */ +export interface CreateChannelOptions { + userProject?: string; +} + +/** + * @typedef {array} CreateChannelResponse + * @property {Channel} 0 The new {@link Channel}. + * @property {object} 1 The full API response. + */ +export type CreateChannelResponse = [Channel, object]; + +/** + * @callback CreateChannelCallback + * @param {?Error} err Request error, if any. + * @param {Channel} channel The new {@link Channel}. + * @param {object} apiResponse The full API response. + */ +export interface CreateChannelCallback { + (err: Error|null, channel: Channel|null, apiResponse: object); +} + + /** * The size of a file (in bytes) must be greater than this number to * automatically trigger a resumable upload. @@ -136,7 +225,7 @@ class Bucket extends ServiceObject { * @name Bucket#userProject * @type {string} */ - userProject: string; + userProject?: string; /** * Cloud Storage uses access control lists (ACLs) to manage object and @@ -299,7 +388,7 @@ class Bucket extends ServiceObject { */ getFilesStream: Function; - constructor(storage: Storage, name: string, options?) { + constructor(storage: Storage, name: string, options?: BucketOptions) { options = options || {}; // Allow for "gs://"-style input, and strip any trailing slashes. @@ -365,17 +454,6 @@ class Bucket extends ServiceObject { this.getFilesStream = paginator.streamify('getFiles'); } - /** - * @typedef {array} CombineResponse - * @property {File} 0 The new {@link File}. - * @property {object} 1 The full API response. - */ - /** - * @callback CombineCallback - * @param {?Error} err Request error, if any. - * @param {File} newFile The new {@link File}. - * @param {object} apiResponse The full API response. - */ /** * Combine multiple files into one new file. * @@ -389,14 +467,7 @@ class Bucket extends ServiceObject { * combined. * @param {string|File} destination The file you would like the * source files combined into. - * @param {object} [options] Configuration options. - * @param {string} [options.kmsKeyName] Resource name of the Cloud KMS key, of - * the form - * `projects/my-project/locations/location/keyRings/my-kr/cryptoKeys/my-key`, - * that will be used to encrypt the object. Overwrites the object - * metadata's `kms_key_name` value, if any. - * @param {string} [options.userProject] The ID of the project which will be - * billed for the request. + * @param {CombineOptions} [options] Configuration options. * @param {CombineCallback} [callback] Callback function. * @returns {Promise} * @@ -422,7 +493,9 @@ class Bucket extends ServiceObject { * const apiResponse = data[1]; * }); */ - combine(sources: string[]|File[], destination, options, callback) { + combine(sources: string[]|File[], destination: string|File, options: CombineOptions): Promise; + combine(sources: string[]|File[], destination: string|File, options: CombineOptions, callback); + combine(sources: string[]|File[], destination: string|File, options: CombineOptions, callback?): Promise | void { if (!is.array(sources) || sources.length < 2) { throw new Error('You must provide at least two source files.'); } @@ -482,25 +555,14 @@ class Bucket extends ServiceObject { }, (err, resp) => { if (err) { - callback(err, null, resp); + callback!(err, null, resp); return; } - callback(null, destination, resp); + callback!(null, destination, resp); }); } - /** - * @typedef {array} CreateChannelResponse - * @property {Channel} 0 The new {@link Channel}. - * @property {object} 1 The full API response. - */ - /** - * @callback CreateChannelCallback - * @param {?Error} err Request error, if any. - * @param {Channel} channel The new {@link Channel}. - * @param {object} apiResponse The full API response. - */ /** * Create a channel that will be notified when objects in this bucket changes. * @@ -510,14 +572,8 @@ class Bucket extends ServiceObject { * @see [Objects: watchAll API Documentation]{@link https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll} * * @param {string} id The ID of the channel to create. - * @param {object} config See a - * [Objects: watchAll request - * body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). - * @param {string} config.address The address where notifications are - * delivered for this channel. - * @param {object} [options] Configuration options. - * @param {string} [options.userProject] The ID of the project which will be - * billed for the request. + * @param {CreateChannelConfig} config Configuration for creating channel. + * @param {CreateChannelOptions} [options] Configuration options. * @param {CreateChannelCallback} [callback] Callback function. * @returns {Promise} * @@ -545,7 +601,10 @@ class Bucket extends ServiceObject { * const apiResponse = data[1]; * }); */ - createChannel(id: string, config, options, callback?) { + createChannel(id: string, config: CreateChannelConfig, options?: CreateChannelOptions): Promise; + createChannel(id: string, config: CreateChannelConfig, callback: CreateChannelCallback); + createChannel(id: string, config: CreateChannelConfig, options: CreateChannelOptions, callback: CreateChannelCallback); + createChannel(id: string, config: CreateChannelConfig, options?: CreateChannelOptions|CreateChannelCallback, callback?: CreateChannelCallback): Promise|void { if (!is.string(id)) { throw new Error('An ID is required to create a channel.'); } @@ -554,7 +613,7 @@ class Bucket extends ServiceObject { throw new Error('An address is required to create a channel.'); } - if (is.fn(options)) { + if (typeof options === 'function') { callback = options; options = {}; } @@ -573,7 +632,7 @@ class Bucket extends ServiceObject { }, (err, apiResponse) => { if (err) { - callback(err, null, apiResponse); + callback!(err, null, apiResponse); return; } @@ -582,7 +641,7 @@ class Bucket extends ServiceObject { channel.metadata = apiResponse; - callback(null, channel, apiResponse); + callback!(null, channel, apiResponse); }); } diff --git a/src/file.ts b/src/file.ts index 206815f56..daa038dfc 100644 --- a/src/file.ts +++ b/src/file.ts @@ -254,7 +254,7 @@ class File extends ServiceObject { bucket: Bucket; storage: Storage; kmsKeyName?: string; - userProject: string; + userProject?: string; name: string; generation?: number; requestQueryObject?: {generation: number}; From 251ab5d8c7dfbc48f8b0f41dbd7f1183d0903e0e Mon Sep 17 00:00:00 2001 From: Jonathan Lui Date: Tue, 11 Sep 2018 15:46:29 -0700 Subject: [PATCH 2/3] gts fix --- src/bucket.ts | 34 +++++++++++++++++++++++++--------- 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/src/bucket.ts b/src/bucket.ts index 92d8c9ca2..accb37143 100644 --- a/src/bucket.ts +++ b/src/bucket.ts @@ -55,7 +55,8 @@ interface BucketOptions { } /** * See a [Objects: - * watchAll request body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). + * watchAll request + * body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). */ interface WatchAllRequest { delimiter: string; @@ -142,7 +143,8 @@ export type CombineResponse = [File, object]; /** * See a [Objects: - * watchAll request body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). + * watchAll request + * body](https://cloud.google.com/storage/docs/json_api/v1/objects/watchAll). * * @typedef {object} CreateChannelConfig * @property {string} address The address where notifications are @@ -493,9 +495,15 @@ class Bucket extends ServiceObject { * const apiResponse = data[1]; * }); */ - combine(sources: string[]|File[], destination: string|File, options: CombineOptions): Promise; - combine(sources: string[]|File[], destination: string|File, options: CombineOptions, callback); - combine(sources: string[]|File[], destination: string|File, options: CombineOptions, callback?): Promise | void { + combine( + sources: string[]|File[], destination: string|File, + options: CombineOptions): Promise; + combine( + sources: string[]|File[], destination: string|File, + options: CombineOptions, callback); + combine( + sources: string[]|File[], destination: string|File, + options: CombineOptions, callback?): Promise|void { if (!is.array(sources) || sources.length < 2) { throw new Error('You must provide at least two source files.'); } @@ -601,10 +609,18 @@ class Bucket extends ServiceObject { * const apiResponse = data[1]; * }); */ - createChannel(id: string, config: CreateChannelConfig, options?: CreateChannelOptions): Promise; - createChannel(id: string, config: CreateChannelConfig, callback: CreateChannelCallback); - createChannel(id: string, config: CreateChannelConfig, options: CreateChannelOptions, callback: CreateChannelCallback); - createChannel(id: string, config: CreateChannelConfig, options?: CreateChannelOptions|CreateChannelCallback, callback?: CreateChannelCallback): Promise|void { + createChannel( + id: string, config: CreateChannelConfig, + options?: CreateChannelOptions): Promise; + createChannel( + id: string, config: CreateChannelConfig, callback: CreateChannelCallback); + createChannel( + id: string, config: CreateChannelConfig, options: CreateChannelOptions, + callback: CreateChannelCallback); + createChannel( + id: string, config: CreateChannelConfig, + options?: CreateChannelOptions|CreateChannelCallback, + callback?: CreateChannelCallback): Promise|void { if (!is.string(id)) { throw new Error('An ID is required to create a channel.'); } From dce7a6d88c90e1f1781fa24f17a3273f49b9443e Mon Sep 17 00:00:00 2001 From: Jonathan Lui Date: Tue, 11 Sep 2018 15:49:00 -0700 Subject: [PATCH 3/3] move DeleteFileRequest docs --- src/bucket.ts | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/bucket.ts b/src/bucket.ts index accb37143..6411d9f77 100644 --- a/src/bucket.ts +++ b/src/bucket.ts @@ -53,6 +53,7 @@ interface MetadataRequest { interface BucketOptions { userProject?: string; } + /** * See a [Objects: * watchAll request @@ -105,6 +106,12 @@ export interface GetFilesRequest { versions?: boolean; } +/** + * @typedef {object} DeleteFilesRequest Query object. See {@link Bucket#getFiles} + * for all of the supported properties. + * @property {boolean} [force] Suppress errors until all files have been + * processed. + */ export interface DeleteFilesRequest extends GetFilesRequest { force?: boolean; } @@ -877,12 +884,7 @@ class Bucket extends ServiceObject { * * @see [Objects: delete API Documentation]{@link https://cloud.google.com/storage/docs/json_api/v1/objects/delete} * - * @param {object} [query] Query object. See {@link Bucket#getFiles} - * for all of the supported properties. - * @param {boolean} [query.force] Suppress errors until all files have been - * processed. - * @param {string} [query.userProject] The ID of the project which will be - * billed for the request. + * @param {DeleteFilesRequest} [query] Query object. See {@link Bucket#getFiles} * @param {DeleteFilesCallback} [callback] Callback function. * @returns {Promise} *