fix: add warning for unsupported keepAcl param in file#copy (#841)

src/file.ts

@@ -295,6 +295,7 @@ export interface FileOptions {
 
 export interface CopyOptions {
   destinationKmsKeyName?: string;
+  keepAcl?: string;
   predefinedAcl?: string;
   token?: string;
   userProject?: string;
@@ -858,6 +859,8 @@ class File extends ServiceObject<File> {
    *     `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} [keepAcl] This parameter is not supported and will be
+   *     removed in the next major.
    * @property {string} [predefinedAcl] Set the ACL for the new file.
    * @property {string} [token] A previously-returned `rewriteToken` from an
    *     unfinished rewrite request.
@@ -984,6 +987,11 @@ class File extends ServiceObject<File> {
       options = optionsOrCallback;
     }
 
+    if (options.hasOwnProperty('keepAcl')) {
+      // TODO: remove keepAcl from interface in next major.
+      emitWarning();
+    }
+
     options = extend(true, {}, options);
     callback = callback || util.noop;
 
@@ -3416,6 +3424,17 @@ promisifyAll(File, {
   ],
 });
 
+let warned = false;
+export function emitWarning() {
+  if (!warned) {
+    warned = true;
+    process.emitWarning(
+      'keepAcl parameter is not supported and will be removed in the next major',
+      'DeprecationWarning'
+    );
+  }
+}
+
 /**
  * Reference to the {@link File} class.
  * @name module:@google-cloud/storage.File

test/file.ts

@@ -345,6 +345,65 @@ describe('File', () => {
   });
 
   describe('copy', () => {
+    describe('depricate `keepAcl`', () => {
+      // tslint:disable-next-line: no-any
+      let STORAGE2: any;
+      // tslint:disable-next-line: no-any
+      let BUCKET2: any;
+      // tslint:disable-next-line: no-any
+      let file2: any;
+      beforeEach(() => {
+        STORAGE2 = {
+          createBucket: util.noop,
+          request: util.noop,
+          // tslint:disable-next-line: no-any
+          makeAuthenticatedRequest(req: {}, callback: any) {
+            if (callback) {
+              (callback.onAuthenticated || callback)(null, req);
+            }
+          },
+          bucket(name: string) {
+            return new Bucket(this, name);
+          },
+        };
+        BUCKET2 = new Bucket(STORAGE, 'bucket-name');
+        file2 = new File(BUCKET, FILE_NAME);
+      });
+
+      it('should warn if `keepAcl` parameter is passed', done => {
+        file.request = util.noop;
+
+        // since --throw-deprication is enabled using try=>catch block
+        try {
+          file.copy('newFile', {keepAcl: 'private'}, assert.ifError);
+        } catch (err) {
+          assert.strictEqual(
+            err.message,
+            'keepAcl parameter is not supported and will be removed in the next major'
+          );
+          assert.strictEqual(err.name, 'DeprecationWarning');
+          done();
+        }
+      });
+
+      it('should warn only once `keepAcl` parameter is passed', done => {
+        file.request = util.noop;
+
+        // since --throw-deprication is enabled using try=>catch block
+        try {
+          file.copy('newFile', {keepAcl: 'private'}, assert.ifError);
+        } catch (err) {
+          assert.strictEqual(
+            err.message,
+            'keepAcl parameter is not supported and will be removed in the next major'
+          );
+          assert.strictEqual(err.name, 'DeprecationWarning');
+        }
+        file2.copy('newFile2', {keepAcl: 'private'}, assert.ifError);
+        done();
+      });
+    });
+
     it('should throw if no destination is provided', () => {
       assert.throws(() => {
         file.copy();