Type definitions for array.prototype.flatmap (#29437)

* Type definitions for array.prototype.flatmap

* array.prototype.flatmap: importing "/auto" extends the Array prototype

types/array.prototype.flatmap/array.prototype.flatmap-tests.ts

@@ -0,0 +1,47 @@
+import flatMap = require("array.prototype.flatmap");
+import "array.prototype.flatmap/auto";
+import flatMapImpl = require("array.prototype.flatmap/implementation");
+import getPolyfill = require("array.prototype.flatmap/polyfill");
+import shim = require("array.prototype.flatmap/shim");
+
+// infers type of the output array from the return type of the callback
+flatMap(["foo"], word => word.split("")); // $ExpectType string[]
+flatMapImpl(["foo"], word => word.split("")); // $ExpectType string[]
+["foo"].flatMap(word => word.split("")); // $ExpectType string[]
+
+// infers the type of the value argument to the callback
+flatMap([1, 2], word => word.split("")); // $ExpectError
+flatMapImpl([1, 2], word => word.split("")); // $ExpectError
+[1, 2].flatMap(word => word.split("")); // $ExpectError
+
+// the callback must return an array
+flatMap([1, 2], word => word); // $ExpectError
+flatMapImpl([1, 2], word => word); // $ExpectError
+[1, 2].flatMap(word => word); // $ExpectError
+
+// the callback accepts an index argument
+flatMap(["foo"], (_, index) => [index]); // $ExpectType number[]
+flatMapImpl(["foo"], (_, index) => [index]); // $ExpectType number[]
+["foo"].flatMap((_, index) => [index]); // $ExpectType number[]
+
+// the callback accepts an argument that refers to the original array
+flatMap(["foo"], (_, __, input) => input); // $ExpectType string[]
+flatMapImpl(["foo"], (_, __, input) => input); // $ExpectType string[]
+["foo"].flatMap((_, __, input) => input); // $ExpectType string[]
+
+// the third argument is used as the calling context for the callback
+flatMap(["foo"], function() { return this.foo; }, { foo: [1, 2] }); // $ExpectType number[]
+flatMapImpl(["foo"], function() { return this.foo; }, { foo: [1, 2] }); // $ExpectType number[]
+["foo"].flatMap(function() { return this.foo; }, { foo: [1, 2] }); // $ExpectType number[]
+
+// assumes that value of `this` in callback is `undefined` by default (this is
+// accurate in strict mode)
+flatMap([1], function() { return [this]; }); // $ExpectType undefined[]
+flatMapImpl([1], function() { return [this]; }); // $ExpectType undefined[]
+[1].flatMap(function() { return [this]; }); // $ExpectType undefined[]
+
+// `getPolyfill` returns a flatMap implementation
+getPolyfill()(["foo"], word => word.split("")); // $ExpectType string[]
+
+// `shim` installs a flatMap implementation in `Array` prototype and returns it
+shim()(["foo"], word => word.split("")); // $ExpectType string[]

types/array.prototype.flatmap/auto.d.ts

@@ -0,0 +1,6 @@
+interface Array<T> {
+    flatMap<U, R extends object | undefined = undefined>(
+        fn: (this: R, x: T, index: number, array: this) => U[],
+        thisArg?: R
+    ): U[];
+}

types/array.prototype.flatmap/implementation.d.ts

@@ -0,0 +1,7 @@
+// This is the same type as the callable signature in `FlatMap` in `index.d.ts`.
+declare function flatMap<A, B, T extends object | undefined = undefined>(
+    xs: ReadonlyArray<A>,
+    fn: (this: T, x: A, index: number, array: A[]) => B[],
+    thisArg?: T
+): B[];
+export = flatMap;

types/array.prototype.flatmap/index.d.ts

@@ -0,0 +1,21 @@
+// Type definitions for array.prototype.flatmap 1.2
+// Project: https://github.com/es-shims/Array.prototype.flatMap#readme
+// Definitions by: Jesse Hallett <https://github.com/hallettj>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 2.3
+
+import flatMapImpl = require("./implementation");
+
+interface FlatMap {
+    <A, B, T extends object | undefined = undefined>(
+        xs: ReadonlyArray<A>,
+        fn: (this: T, x: A, index: number, array: A[]) => B[],
+        thisArg?: T
+    ): B[];
+    getPolyfill(): typeof flatMapImpl;
+    implementation: typeof flatMapImpl;
+    shim(): typeof flatMapImpl;
+}
+
+declare const flatMap: FlatMap;
+export = flatMap;

types/array.prototype.flatmap/polyfill.d.ts

@@ -0,0 +1,4 @@
+import flatMap = require("./implementation");
+
+declare function getPolyfill(): typeof flatMap;
+export = getPolyfill;

types/array.prototype.flatmap/shim.d.ts

@@ -0,0 +1,4 @@
+import flatMap = require("./implementation");
+
+declare function shim(): typeof flatMap;
+export = shim;

types/array.prototype.flatmap/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../",
+        "typeRoots": [
+            "../"
+        ],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "array.prototype.flatmap-tests.ts",
+        "auto.d.ts",
+        "implementation.d.ts",
+        "index.d.ts",
+        "polyfill.d.ts",
+        "shim.d.ts"
+    ]
+}

types/array.prototype.flatmap/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }