Refactor type-declarations (#114)

* Fix incorrect type-declarations

* Add a proper return-type

* Refactor the documentation-comments

* Downgrade the `package-lock.json` to v1

* Add missing export-statement

* Remove redundant type-declaration

* Make argument-name more apropriate

* Add a test for checking whether `gulp-replace` works with typescript

* Create separate type-declarations for `Replacer` and `Options`

* Make `skipBinary` optional

* Create type-declarations for the `file`-property

* Add documentation-comments

* Add tests for the new type-declarations

* Increase timeout of slow tests

* Add `@types/vinyl` to the dependencies

index.d.ts

@@ -1,23 +1,53 @@
-/**
- * replace
- * gulp-replace can be called with a string or regex.
- *
- * @param search       The string or regex to search for
- *
- * @param _replacement The replacement string or function.
- *                     <p>If replacement is a function, it will be called once for each match and will be passed the string
- *                     that is to be replaced. The value of `this.file` will be equal to the vinyl instance for the file
- *                     being processed.</p>
- *                     Read more at
- *                     <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter">String.prototype.replace() at MDN web docs</a>
- *
- * @param options     `options.skipBinary` will be equal to `true` by default.
- *                     <p>Skip binary files. This option is true by default. If
- *                     you want to replace content in binary files, you must explicitly set it to false</p>
- *
- */
-export declare function replace(
-    search: string | RegExp,
-    _replacement: string | (() => string) | ((search: string, ...args: any[]) => string),
-    options?: { skipBinary: boolean }
-): any; /* The type of return value should not be `any`, but I could not find the types definition of  */
+/// <reference types="node" />
+import type File = require("vinyl");
+
+/**
+ * Represents options for `gulp-replace`.
+ */
+interface Options {
+    /**
+     * A value indicating whether binary files should be skipped.
+     */
+    skipBinary?: boolean
+}
+
+/**
+ * The context of the replacer-function.
+ */
+interface ReplacerContext {
+    /**
+     * The file being processed.
+     */
+    file: File
+}
+
+/**
+ * Represents a method for replacing contents of a vinyl-file.
+ */
+type Replacer = (this: ReplacerContext, match: string, ...args: any[]) => string;
+
+/**
+ * Searches and replaces a portion of text using a `string` or a `RegExp`.
+ *
+ * @param search       The `string` or `RegExp` to search for.
+ *
+ * @param replacement  The replacement string or a function for generating a replacement.
+ *
+ *                     If `replacement` is a function, it will be called once for each match and will be passed the string
+ *                     that is to be replaced. The value of `this.file` will be equal to the vinyl instance for the file
+ *                     being processed.
+ *
+ *                     Read more at [`String.prototype.replace()` at MDN web docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Specifying_a_string_as_a_parameter").
+ *
+ * @param options      `options.skipBinary` will be equal to `true` by default.
+ *
+ *                     Skip binary files. This option is `true` by default. If
+ *                     you want to replace content in binary files, you must explicitly set it to `false`.
+ */
+declare function replace(
+    search: string | RegExp,
+    replacement: string | Replacer,
+    options?: Options
+): NodeJS.ReadWriteStream;
+
+export = replace;

package.json

@@ -3,14 +3,19 @@
   "version": "1.1.1",
   "description": "A string replace plugin for gulp",
   "dependencies": {
+    "@types/node": "^14.14.41",
+    "@types/vinyl": "^2.0.4",
     "istextorbinary": "^3.0.0",
     "replacestream": "^4.0.3",
     "yargs-parser": ">=5.0.0-security.0"
   },
   "devDependencies": {
     "concat-stream": "^2.0.0",
     "mocha": "^7.0.0",
+    "npm-which": "^3.0.1",
     "should": "^13.2.3",
+    "ts-node": "^9.1.1",
+    "typescript": "^4.2.4",
     "vinyl": "^2.2.1"
   },
   "scripts": {

test/fixtures/script.ts

@@ -0,0 +1,16 @@
+import replacePlugin = require('../..');
+
+replacePlugin(/.*/, '');
+replacePlugin('hello', 'world');
+
+replacePlugin(/.*/, () => 'test');
+replacePlugin('', (match, ...args) => match + '-test' + args[0]);
+
+replacePlugin(
+    '',
+    function (match)
+    {
+        console.log(match);
+        console.log(this.file.basename);
+        return '';
+    })

test/realworld.js

@@ -1,7 +1,10 @@
 'use strict';
 
 const replacePlugin = require('../');
+const { spawnSync } = require('child_process');
 const fs = require('fs');
+const npmWhich = require('npm-which');
+const { join } = require('path');
 const should = require('should');
 const File = require('vinyl');
 
@@ -67,5 +70,18 @@ describe('gulp-replace', function() {
       stream.write(file);
       stream.end();
     });
+
+    it('run `gulp-replace` using typescript', function() {
+      this.slow(5 * 1000);
+      this.timeout(10 * 1000);
+
+      const spawnResult = spawnSync(
+        npmWhich(__dirname).sync('ts-node'),
+        [
+          join(__dirname, 'fixtures', 'script.ts')
+        ]);
+
+      should.equal(spawnResult.status, 0);
+    });
   });
 });