Tweaks to work better in practice with freeway

* Generate `composeMiddleware` overloads up to 30 arguments.
* Use file extensions in `import`s.
* Use `Simplify` in the return type of `composeMiddleware` for
  better ergonomics.
* Add `extends {}` to the type parameters of a `Middleware` function--I
  don't actually remember why, but the types didn't infer correctly
  otherwise.
* Use `const`s instead of `function`s for middleware functions. The
  `@type` tag doesn't apply correctly to a `function` declaration--which
  makes sense, since there's no equivalent syntax that would do it in
  TypeScript: microsoft/TypeScript#27387

Author: Peeja

scripts/generateComposeMiddleware.js

@@ -3,7 +3,7 @@ import ts from 'typescript'
 import * as prettier from 'prettier'
 
 // The maximum number of arguments to generate overloads for.
-const MAX_ARGUMENTS = 20
+const MAX_ARGUMENTS = 30
 
 /**
  * Simply passes the value {@link x} to the function {@param fn} and returns the
@@ -40,7 +40,7 @@ const declarations = [
       EnvOf,
       Middleware,
       RequiredContextOf,
-    } from './bindings'
+    } from './bindings.js'
 
     /**
      * Returns the result of satisfying the {@link Requirements} with the
@@ -50,6 +50,12 @@ const declarations = [
       With extends Pick<Requirements, keyof Requirements & keyof With>
         ? Omit<Requirements, keyof With>
         : never
+
+    /**
+     * Forces TypeScript to resolve a complex type into a simple single object
+     * type. This makes the type of a composed middleware much easier to read.
+     */
+    type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
   `,
 
   /* typescript */ `
@@ -87,6 +93,7 @@ function createComposeMiddlewareOverloadDeclaration (argCount) {
     undefined,
     'composeMiddleware',
     [
+      // Type parameters
       ...ns.flatMap((n) => {
         return [
           ts.factory.createTypeParameterDeclaration(
@@ -125,6 +132,8 @@ function createComposeMiddlewareOverloadDeclaration (argCount) {
         ]
       })
     ],
+
+    // Function parameters
     ns.map((n) =>
       ts.factory.createParameterDeclaration(
         undefined,
@@ -135,31 +144,39 @@ function createComposeMiddlewareOverloadDeclaration (argCount) {
         undefined
       )
     ),
+
+    // Return type
     ts.factory.createTypeReferenceNode('Middleware', [
-      ts.factory.createIntersectionTypeNode(
-        ns.map((n) =>
-          withBinding(
-            ts.factory.createTypeReferenceNode('RequiredContextOf', [
-              ts.factory.createTypeReferenceNode(`M${n}`)
-            ]),
-            (requiredContext) =>
-              n === 1
-                ? requiredContext
-                : ts.factory.createTypeReferenceNode('Satisfy', [
-                  requiredContext,
-                  ts.factory.createTypeReferenceNode(`M${n - 1}C`)
-                ])
+      ts.factory.createTypeReferenceNode('Simplify', [
+        ts.factory.createIntersectionTypeNode(
+          ns.map((n) =>
+            withBinding(
+              ts.factory.createTypeReferenceNode('RequiredContextOf', [
+                ts.factory.createTypeReferenceNode(`M${n}`)
+              ]),
+              (requiredContext) =>
+                n === 1
+                  ? requiredContext
+                  : ts.factory.createTypeReferenceNode('Satisfy', [
+                    requiredContext,
+                    ts.factory.createTypeReferenceNode(`M${n - 1}C`)
+                  ])
+            )
           )
         )
-      ),
-      ts.factory.createTypeReferenceNode(`M${ns[ns.length - 1]}C`),
-      ts.factory.createIntersectionTypeNode(
-        ns.map((n) =>
-          ts.factory.createTypeReferenceNode('EnvOf', [
-            ts.factory.createTypeReferenceNode(`M${n}`)
-          ])
+      ]),
+      ts.factory.createTypeReferenceNode('Simplify', [
+        ts.factory.createTypeReferenceNode(`M${ns[ns.length - 1]}C`)
+      ]),
+      ts.factory.createTypeReferenceNode('Simplify', [
+        ts.factory.createIntersectionTypeNode(
+          ns.map((n) =>
+            ts.factory.createTypeReferenceNode('EnvOf', [
+              ts.factory.createTypeReferenceNode(`M${n}`)
+            ])
+          )
         )
-      )
+      ])
     ]),
     undefined
   )

src/bindings.d.ts

@@ -80,7 +80,7 @@ export type Middleware<
    * handler.
    * @template HandlerEnv The environment keys used by the wrapped handler.
    */
-  <HandlerRequiredContext, HandlerEnv>(
+  <HandlerRequiredContext extends {}, HandlerEnv extends {}>(
     h: Handler<AddedContext & HandlerRequiredContext, Env & HandlerEnv>
   ) => Handler<RequiredContext & HandlerRequiredContext, Env & HandlerEnv>