Refine chain definition, add test cases (#3680)

* Refine chain definition, add test cases

* Use 'Array' instead of '[]'

* Missed one place

* refactor some test cases, additional comment on definition

Co-authored-by: Andrew Smith <andrewsmith@alumni.stanford.edu>

definitions/npm/ramda_v0.26.x/flow_v0.104.x-/ramda_v0.26.x.js

@@ -652,8 +652,17 @@ declare module ramda {
     x: E,
   ): (xs: Array<E>) => Array<E>;
 
-  declare function chain<A, B>(f: (x: A) => B[], xs: A[]): B[]
-  declare function chain<A, B>(f: (x: A) => B[]): (xs: A[]) => B[]
+  declare function chain<A, B>(f: (x: A) => Array<B>, xs: $ReadOnlyArray<A>): Array<B>;
+  declare function chain<A, B>(f: (x: A) => Array<B>): (xs: $ReadOnlyArray<A>) => Array<B>;
+
+  // Additional chain functionality documented at https://ramdajs.com/docs/#chain:
+  //
+  // Dispatches to the chain method of the second argument, if present, according to the FantasyLand Chain spec (https://github.com/fantasyland/fantasy-land#chain).
+  //
+  // If second argument is a function, chain(f, g)(x) is equivalent to f(g(x), x).
+  //
+  // Acts as a transducer if a transformer is given in list position.
+  declare function chain<A, B, R>(f: (x: A, y: B) => R, g: (y: B) => A):(y: B) => R;
 
   declare function concat<A, B>(x: $ReadOnlyArray<A>, y: $ReadOnlyArray<B>): Array<A | B>;
   declare function concat<A, B>(x: $ReadOnlyArray<A>): CurriedFunction1<$ReadOnlyArray<B>, Array<A | B>>;

definitions/npm/ramda_v0.26.x/flow_v0.104.x-/test_ramda_v0.26.x_list.js

@@ -4,14 +4,16 @@ import _, {
   type RefineFilter,
   adjust,
   append,
+  chain,
   compose,
   concat,
   contains,
   curry,
   filter,
   find,
-  includes,
   groupBy,
+  includes,
+  last,
   length,
   nth,
   pipe,
@@ -821,6 +823,34 @@ const str: string = "hello world";
     y: b
   }))([1, 2, 3])(["1", "2", "3"]);
 
+  describe('chain', () => {
+    it('should accept read only list as input', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const duplicate = n => [n, n];
+      const result1: Array<string> = chain(duplicate, arr);
+      const result2: Array<string> = chain(duplicate)(arr);
+    });
+
+    it('should fail when input out type mismatch', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const castType = n => (parseInt(n): number);
+      //$ExpectError
+      const result: Array<string> = chain(castType, arr);
+    });
+
+    it('should take second argument as function', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const result: Array<?string> = chain(append, x => x[x.length - 1])(arr)
+    });
+
+    it('should error out when second arugment is function but type mismatches', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const castType = n => (parseInt(n): number);
+      //$ExpectError
+      const result: Array<string> = chain(append, castType)(arr)
+    });
+  });
+              
   describe('nth', () => {
     it('should get a maybe type back on input is an array of given types', () => {
       const nthxs1: ?number = nth(2, [1,2,3]);

definitions/npm/ramda_v0.26.x/flow_v0.76.x-v0.103.x/ramda_v0.26.x.js

@@ -617,8 +617,17 @@ declare module ramda {
     x: E,
   ): (xs: Array<E>) => Array<E>;
 
-  declare function chain<A, B>(f: (x: A) => B[], xs: A[]): B[]
-  declare function chain<A, B>(f: (x: A) => B[]): (xs: A[]) => B[]
+  declare function chain<A, B>(f: (x: A) => Array<B>, xs: $ReadOnlyArray<A>): Array<B>
+  declare function chain<A, B>(f: (x: A) => Array<B>): (xs: $ReadOnlyArray<A>) => Array<B>
+
+  // Additional chain functionality documented at https://ramdajs.com/docs/#chain:
+  //
+  // Dispatches to the chain method of the second argument, if present, according to the FantasyLand Chain spec (https://github.com/fantasyland/fantasy-land#chain).
+  //
+  // If second argument is a function, chain(f, g)(x) is equivalent to f(g(x), x).
+  //
+  // Acts as a transducer if a transformer is given in list position.
+  declare function chain<A, B, R>(f: (x: A, y: B) => R, g: (y: B) => A):(y: B) => R;
 
   declare function concat<A, B>(x: $ReadOnlyArray<A>, y: $ReadOnlyArray<B>): Array<A | B>;
   declare function concat<A, B>(x: $ReadOnlyArray<A>): CurriedFunction1<$ReadOnlyArray<B>, Array<A | B>>;

definitions/npm/ramda_v0.26.x/flow_v0.76.x-v0.103.x/test_ramda_v0.26.x_list.js

@@ -4,6 +4,7 @@ import _, {
   type RefineFilter,
   adjust,
   append,
+  chain,
   compose,
   concat,
   contains,
@@ -12,6 +13,7 @@ import _, {
   find,
   groupBy,
   includes,
+  last,
   length,
   nth,
   pipe,
@@ -701,6 +703,34 @@ const str: string = "hello world";
     y: b
   }))([1, 2, 3])(["1", "2", "3"]);
 
+  describe('chain', () => {
+    it('should accept read only list as input', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const duplicate = n => [n, n];
+      const result1: Array<string> = chain(duplicate, arr);
+      const result2: Array<string> = chain(duplicate)(arr);
+    });
+
+    it('should fail when input out type mismatch', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const castType = n => (parseInt(n): number);
+      //$ExpectError
+      const result: Array<string> = chain(castType, arr);
+    });
+
+    it('should take second argument as function', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const result: Array<?string> = chain(append, x => x[x.length -1])(arr)
+    });
+
+    it('should error out when second arugment is function but type mismatches', () => {
+      const arr:$ReadOnlyArray<string> = ['1', '2', '3'];
+      const castType = n => (parseInt(n): number);
+      //$ExpectError
+      const result: Array<string> = chain(append, castType)(arr)
+    });
+  });
+
   describe('nth', () => {
     it('should get a maybe type back on input is an array of given types', () => {
       const nthxs1: ?number = nth(2, [1,2,3]);