Merge pull request #24204 from Nayni/graphql-resolve-batch-jsdocs

graphql-resolve-batch: improve test coverage and add jsdocs

types/graphql-resolve-batch/graphql-resolve-batch-tests.ts

@@ -16,6 +16,14 @@ interface SomeTestResult {
     someTestResultProp: string;
 }
 
+const batchFunction = (sources: ReadonlyArray<SomeTestSource>) => {
+    const someTestResult: SomeTestResult = {
+        someTestResultProp: "Hello"
+    };
+
+    return sources.map(source => someTestResult);
+};
+
 const asyncBatchFunction = async (sources: ReadonlyArray<SomeTestSource>) => {
     return new Promise<SomeTestResult[]>(resolve => {
         const res = [
@@ -27,19 +35,35 @@ const asyncBatchFunction = async (sources: ReadonlyArray<SomeTestSource>) => {
     });
 };
 
+const asyncBatchFunctionWhenTReturnIsArray = async (
+    sources: ReadonlyArray<SomeTestSource>
+) => {
+    const sourceBatches = sources.map(() => {
+        return new Promise<SomeTestResult[]>(resolve => {
+            const res = [
+                {
+                    someTestResultProp: ""
+                }
+            ];
+            resolve(res);
+        });
+    });
+
+    return Promise.all(sourceBatches);
+};
+
+// $ExpectType ResolverFunction<SomeTestSource, any, any, SomeTestResult>
 const withSourceAndResultTyped = createBatchResolver<
     SomeTestSource,
     SomeTestResult
 >((sources, _, __) => {
-    return sources.map(source => {
-        const res: SomeTestResult = {
-            someTestResultProp: ""
-        };
+    // $ExpectType ReadonlyArray<SomeTestSource>
+    const verifySources = sources;
 
-        return res;
-    });
+    return batchFunction(sources);
 });
 
+// $ExpectType ResolverFunction<SomeTestSource, any, any, SomeTestResult>
 const withSourceAndResultTypedAsPromise = createBatchResolver<
     SomeTestSource,
     SomeTestResult
@@ -50,6 +74,7 @@ const withSourceAndResultTypedAsPromise = createBatchResolver<
     return result;
 });
 
+// $ExpectType ResolverFunction<SomeTestSource, SomeTestArgs, any, SomeTestResult>
 const withSourceAndArgsAndResultTyped = createBatchResolver<
     SomeTestSource,
     SomeTestResult,
@@ -64,6 +89,7 @@ const withSourceAndArgsAndResultTyped = createBatchResolver<
     return result;
 });
 
+// $ExpectType ResolverFunction<SomeTestSource, SomeTestArgs, SomeTestContext, SomeTestResult>
 const withSourceAndArgsAndContextTyped = createBatchResolver<
     SomeTestSource,
     SomeTestResult,
@@ -80,3 +106,13 @@ const withSourceAndArgsAndContextTyped = createBatchResolver<
     const result = await asyncBatchFunction(sources);
     return result;
 });
+
+// $ExpectType ResolverFunction<SomeTestSource, any, any, SomeTestResult[]>
+const withResultIsArray = createBatchResolver<SomeTestSource, SomeTestResult[]>(
+    (sources, _, __) => {
+        // $ExpectType ReadonlyArray<SomeTestSource>
+        const verifySources = sources;
+
+        return asyncBatchFunctionWhenTReturnIsArray(sources);
+    }
+);

types/graphql-resolve-batch/index.d.ts

@@ -4,6 +4,22 @@
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.3
 
+/**
+ * Creates a GraphQL.js field resolver that batches together multiple resolves
+ * together that share the *exact* same GraphQL field selection.
+ *
+ * Note:
+ *  The batchResolveFunction you supply always expects you to return an array of TReturn (or a promise with this array).
+ *  This is because you will have to return a TReturn for every source given to you by the batch function.
+ *  For an example of this please see the examples in the original project repository:
+ *  https://github.com/calebmer/graphql-resolve-batch/tree/master/examples
+ *
+ * @template TSource The original type of a single source.
+ * @template TReturn The return type of the field resolver.
+ * @template TArgs The type of supplied arguments.
+ * @template TContext The type of the current resolver context.
+ * @param batchResolveFn A batch function to resolve all fields for the given sources in a single batch.
+ */
 export function createBatchResolver<
     TSource,
     TReturn,
@@ -13,12 +29,19 @@ export function createBatchResolver<
     batchResolveFn: BatchResolveFunction<TSource, TArgs, TContext, TReturn>
 ): ResolverFunction<TSource, TArgs, TContext, TReturn>;
 
+/**
+ * The resulting field resolver that batches together multiple resolves.
+ * Graphql-resolve-batch will always return a promise for this resulting resolver.
+ */
 export type ResolverFunction<TSource, TArgs, TContext, TReturn> = (
     source: TSource,
     args: TArgs,
     context: TContext
-) => Promise<TReturn> | Promise<TReturn[]>;
+) => Promise<TReturn>;
 
+/**
+ * A batch function to resolve all fields for the given sources in a single batch.
+ */
 export type BatchResolveFunction<TSource, TArgs, TContext, TReturn> = (
     sources: ReadonlyArray<TSource>,
     args: TArgs,