feat!: Prefer symlink property set on Vinyl object over its path

lib/symlink/prepare.js

@@ -36,7 +36,8 @@ function prepareSymlink(folderResolver, optResolver) {
     file.cwd = cwd;
     file.base = basePath;
     // This is the path we are linking *TO*
-    file.symlink = file.path;
+    // Use `file.symlink` if it was set in the pipeline
+    file.symlink = file.symlink || file.path;
     file.path = writePath;
     // We have to set contents to null for a link
     // Otherwise `isSymbolic()` returns false

test/dest.js

@@ -1218,7 +1218,7 @@ describeStreams('.dest()', function (stream) {
     pipeline([from([file]), vfs.dest(outputBase)], assert);
   });
 
-  it('does not pass options on to stream.Tranform', function (done) {
+  it('does not pass options on to stream', function (done) {
     var file = new File({
       base: inputBase,
       path: inputPath,

test/src.js

@@ -801,7 +801,7 @@ describeStreams('.src()', function (stream) {
     );
   });
 
-  it('does not pass options on to stream.Transform', function (done) {
+  it('does not pass options on to stream', function (done) {
     // Reference: https://github.com/gulpjs/vinyl-fs/issues/153
     var read = sinon.fake.returns(false);
 

test/symlink.js

@@ -223,6 +223,51 @@ describeStreams('symlink stream', function (stream) {
     );
   });
 
+  it('will create symlinks with different names if property set in pipeline', function (done) {
+    var file = new File({
+      base: inputBase,
+      path: inputPath,
+      contents: null,
+    });
+
+    var renamed = 'renamed-symlink.txt';
+
+    function assert(files) {
+      var outputLink = fs.readlinkSync(path.join(outputBase, renamed));
+
+      expect(files.length).toEqual(1);
+      expect(files).toContain(file);
+      expect(files[0].base).toEqual(outputBase);
+      expect(files[0].path).toEqual(path.join(outputBase, renamed));
+      expect(files[0].symlink).toEqual(outputLink);
+      expect(files[0].isSymbolic()).toBe(true);
+      expect(outputLink).toEqual(inputPath);
+    }
+
+    pipeline(
+      [
+        from([file]),
+        new stream.Transform({
+          objectMode: true,
+          transform: function (file, enc, cb) {
+            if (typeof enc === 'function') {
+              cb = enc;
+            }
+
+            // User can stash the file.path on the symlink before they rename the file
+            file.symlink = file.path;
+            // Then they can rename the file
+            file.basename = renamed;
+            cb(null, file);
+          },
+        }),
+        vfs.symlink(outputBase),
+        concatArray(assert),
+      ],
+      done
+    );
+  });
+
   it('creates a link for a file with streaming contents', function (done) {
     var file = new File({
       base: inputBase,
@@ -971,7 +1016,7 @@ describeStreams('symlink stream', function (stream) {
     });
   });
 
-  it('does not pass options on to through2', function (done) {
+  it('does not pass options on to stream', function (done) {
     var file = new File({
       base: inputBase,
       path: inputPath,