feat(code-gen): drop R.files()

BREAKING CHANGE:
- Use `R.body()` instead of `R.files()`
- When using the Koa router, change usages of `ctx.validatedFiles` with `ctx.validatedBody`
- Auto-generated type names for files inputs like `PostSetHeaderImageFiles` will be renamed to `PostSetHeaderImageBody`.
- Executing this change on the server doesn't require immediate regeneration of api clients. The way they currently send files is compatible.

Author: dirkdev98

docs/features/file-handling.md

@@ -1,7 +1,8 @@
 # File handling
 
 Compas also comes with various utilities across the stack to handle files in a
-consistent way.
+consistent way. See the [file-handling](/examples/file-handling.html) example
+for a project implementing this.
 
 ## Generated router & validators
 
@@ -13,20 +14,29 @@ const T = new TypeCreator();
 const R = T.router("/");
 
 R.post("/upload")
-  .files({
+  .body({
     myFile: T.file(),
   })
   .response({ success: true });
 
 R.get("/download").response(T.file());
 ```
 
-Files are handled separately by the generator and validators, and are put on
-`ctx.validatedFiles` with help from
-[formidable](https://www.npmjs.com/package/formidable). In the generated api
-clients we generate the correct type (`ReadableStream` or `Blob`) depending on
-the context. And allow for setting custom file parsing options
-`createBodyParser` provided by `@compas/server`
+Files are handled like any other 'POST'-body in Compas, but have some
+restrictions. When a `T.file()` is used, we automatically switch the request
+encoding to use `multipart/form-data` instead of `application/json`. We also add
+restrictions on what other fields we can accept in the same request body. This
+is limited to only use 'simple' types like `T.uuid()`, `T.string()`,
+`T.number()`, `T.bool()`.
+
+The generated api clients automatically determine which type it should generated
+for the target library and runtime. For Fetch clients we use `Blob`, but for an
+Axios & Node.js target, we generate a `ReadableStream` based type.
+
+The default body parser created via `createBodyParser`, from `@compas/server`,
+doesn't parse `multipart/form-data` by default. You can enable this via the
+`multipart: true` option, and customize limitations via the `multipartOptions`
+option.
 
 ## Saving files
 

gen/code-gen.js

@@ -631,7 +631,6 @@ export function extendWithCodeGen(generator) {
         query: T.reference("structure", "referenceDefinition").optional(),
         params: T.reference("structure", "referenceDefinition").optional(),
         body: T.reference("structure", "referenceDefinition").optional(),
-        files: T.reference("structure", "referenceDefinition").optional(),
         response: T.reference("structure", "referenceDefinition").optional(),
         invalidations: [
           T.reference("structure", "routeInvalidationDefinition"),

packages/code-gen/src/api-client/generator.js

@@ -121,7 +121,6 @@ export function apiClientGenerator(generateContext) {
     const types = {
       params: route.params,
       query: route.query,
-      files: route.files,
       body: route.body,
       response: route.response,
     };

packages/code-gen/src/api-client/js-axios.js

@@ -181,10 +181,6 @@ export function jsAxiosGenerateFunction(
       }} body`,
     );
   }
-  if (route.files) {
-    args.push("files");
-    fileWrite(file, `@param {${contextNames.filesTypeName}} files`);
-  }
 
   // Allow overwriting any request config
   args.push("requestConfig");
@@ -209,8 +205,8 @@ export function jsAxiosGenerateFunction(
     )}(${args.join(", ")})`,
   );
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
-    const parameter = route.body ? "body" : "files";
+  if (route.metadata?.requestBodyType === "form-data") {
+    const parameter = "body";
 
     fileWrite(
       file,
@@ -225,7 +221,7 @@ export function jsAxiosGenerateFunction(
       generateContext.structure,
 
       // @ts-expect-error
-      route.body ?? route.files,
+      route.body,
     );
 
     for (const key of Object.keys(type.keys)) {
@@ -278,15 +274,15 @@ export function jsAxiosGenerateFunction(
     fileWrite(file, `params: query,`);
   }
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
+  if (route.metadata?.requestBodyType === "form-data") {
     fileWrite(file, `data,`);
   }
 
   if (route.body && route.metadata?.requestBodyType !== "form-data") {
     fileWrite(file, `data: body,`);
   }
 
-  if (route.files) {
+  if (route.metadata?.requestBodyType === "form-data") {
     fileWrite(
       file,
       `headers: typeof data.getHeaders === "function" ? data.getHeaders() : {},`,

packages/code-gen/src/api-client/js-fetch.js

@@ -205,10 +205,6 @@ export function jsFetchGenerateFunction(
       }} body`,
     );
   }
-  if (route.files) {
-    args.push("files");
-    fileWrite(file, `@param {${contextNames.filesTypeName}} files`);
-  }
 
   // Allow overwriting any request config
   args.push("requestConfig");
@@ -235,8 +231,8 @@ export function jsFetchGenerateFunction(
     )}(${args.join(", ")})`,
   );
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
-    const parameter = route.body ? "body" : "files";
+  if (route.metadata?.requestBodyType === "form-data") {
+    const parameter = "body";
     fileWrite(
       file,
       `const data = ${parameter} instanceof FormData ? ${parameter} : new FormData();`,
@@ -250,7 +246,7 @@ export function jsFetchGenerateFunction(
       generateContext.structure,
 
       // @ts-expect-error
-      route.body ?? route.files,
+      route.body,
     );
 
     for (const key of Object.keys(type.keys)) {
@@ -339,7 +335,7 @@ export function jsFetchGenerateFunction(
 
   fileWrite(file, `method: "${route.method}",`);
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
+  if (route.metadata?.requestBodyType === "form-data") {
     fileWrite(file, `body: data,`);
   }
 

packages/code-gen/src/api-client/react-query.js

@@ -229,25 +229,6 @@ export function reactQueryGenerateFunction(
     }
   }
 
-  if (route.files) {
-    const files = structureResolveReference(
-      generateContext.structure,
-      route.files,
-    );
-    if (files.type !== "object") {
-      fileWrite(file, "\n\n");
-      fileWrite(
-        file,
-        fileFormatInlineComment(
-          file,
-          `Skipped generation of '${hookName}' since a custom files type is used.`,
-        ),
-      );
-      fileWrite(file, "\n\n");
-      return;
-    }
-  }
-
   // Import the corresponding api client function.
   const importCollector = JavascriptImportCollector.getImportCollector(file);
   importCollector.destructure("./apiClient", `${apiName}`);
@@ -278,7 +259,6 @@ export function reactQueryGenerateFunction(
       contextNames.paramsTypeName,
       contextNames.queryTypeName,
       contextNames.bodyTypeName,
-      contextNames.filesTypeName,
       withRequestConfig
         ? `{ requestConfig?: ${
             distilledTargetInfo.isAxios
@@ -404,33 +384,6 @@ export function reactQueryGenerateFunction(
         .join(", ")} }, `;
     }
 
-    if (route.files) {
-      /** @type {import("../generated/common/types.d.ts").StructureObjectDefinition} */
-      // @ts-expect-error
-      const files = structureResolveReference(
-        generateContext.structure,
-        route.files,
-      );
-
-      result += `{ ${Object.keys(files.keys)
-        .map((it) => {
-          if (
-            defaultToNull &&
-            referenceUtilsGetProperty(
-              generateContext,
-              files.keys[it],
-              ["isOptional"],
-              false,
-            )
-          ) {
-            return `"${it}": ${prefix}["${it}"] ?? null`;
-          }
-
-          return `"${it}": ${prefix}["${it}"]`;
-        })
-        .join(", ")} }, `;
-    }
-
     if (withRequestConfig) {
       result += `${prefix}?.requestConfig`;
     }
@@ -463,8 +416,7 @@ export function reactQueryGenerateFunction(
     );
 
     // When no arguments are required, the whole opts object is optional
-    const routeHasMandatoryInputs =
-      route.params || route.query || route.body || route.files;
+    const routeHasMandatoryInputs = route.params || route.query || route.body;
 
     fileWrite(file, `opts: `);
     fileWrite(
@@ -786,7 +738,7 @@ function reactQueryCheckIfRequiredVariablesArePresent(generateContext, route) {
 function reactQueryGetRequiredFields(generateContext, route) {
   const keysAffectingEnabled = [];
 
-  for (const key of ["params", "query", "body", "files"]) {
+  for (const key of ["params", "query", "body"]) {
     if (!route[key]) {
       continue;
     }

packages/code-gen/src/api-client/ts-axios.js

@@ -150,9 +150,6 @@ export function tsAxiosGenerateFunction(
       }`,
     );
   }
-  if (route.files) {
-    args.push(`files: ${contextNames.filesTypeName}`);
-  }
 
   // Allow overwriting any request config
   args.push(`requestConfig?: AxiosRequestConfig`);
@@ -167,8 +164,8 @@ export function tsAxiosGenerateFunction(
     )}(${args.join(", ")}): Promise<${contextNames.responseTypeName}>`,
   );
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
-    const parameter = route.body ? "body" : "files";
+  if (route.metadata?.requestBodyType === "form-data") {
+    const parameter = "body";
 
     fileWrite(
       file,
@@ -183,7 +180,7 @@ export function tsAxiosGenerateFunction(
       generateContext.structure,
 
       // @ts-expect-error
-      route.body ?? route.files,
+      route.body,
     );
 
     for (const key of Object.keys(type.keys)) {
@@ -241,7 +238,7 @@ export function tsAxiosGenerateFunction(
     fileWrite(file, `params: query,`);
   }
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
+  if (route.metadata?.requestBodyType === "form-data") {
     fileWrite(file, `data,`);
 
     if (distilledTargetInfo.isReactNative) {

packages/code-gen/src/api-client/ts-fetch.js

@@ -208,9 +208,6 @@ export function tsFetchGenerateFunction(
       }`,
     );
   }
-  if (route.files) {
-    args.push(`files: ${contextNames.filesTypeName}`);
-  }
 
   // Allow overwriting any request config
   args.push(`requestConfig?: RequestInit`);
@@ -227,8 +224,8 @@ export function tsFetchGenerateFunction(
     }>`,
   );
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
-    const parameter = route.body ? "body" : "files";
+  if (route.metadata?.requestBodyType === "form-data") {
+    const parameter = "body";
 
     fileWrite(
       file,
@@ -243,7 +240,7 @@ export function tsFetchGenerateFunction(
       generateContext.structure,
 
       // @ts-expect-error
-      route.body ?? route.files,
+      route.body,
     );
 
     for (const key of Object.keys(type.keys)) {
@@ -337,7 +334,7 @@ export function tsFetchGenerateFunction(
 
   fileWrite(file, `method: "${route.method}",`);
 
-  if (route.files || route.metadata?.requestBodyType === "form-data") {
+  if (route.metadata?.requestBodyType === "form-data") {
     fileWrite(file, `body: data,`);
 
     if (distilledTargetInfo.isReactNative) {

packages/code-gen/src/builders/RouteBuilder.d.ts

@@ -15,9 +15,6 @@ export class RouteBuilder extends TypeBuilder {
   bodyBuilder:
     | import("../../types/advanced-types.js").TypeBuilderLike
     | undefined;
-  filesBuilder:
-    | import("../../types/advanced-types.js").TypeBuilderLike
-    | undefined;
   responseBuilder:
     | import("../../types/advanced-types.js").TypeBuilderLike
     | undefined;
@@ -49,11 +46,6 @@ export class RouteBuilder extends TypeBuilder {
    * @returns {RouteBuilder}
    */
   body(builder: import("../../index").TypeBuilderLike): RouteBuilder;
-  /**
-   * @param {import("../../index").TypeBuilderLike} builder
-   * @returns {RouteBuilder}
-   */
-  files(builder: import("../../index").TypeBuilderLike): RouteBuilder;
   /**
    * Specify routes that can be invalidated when this route is called.
    *
@@ -93,9 +85,6 @@ export class RouteCreator {
   bodyBuilder:
     | import("../../types/advanced-types.js").TypeBuilderLike
     | undefined;
-  filesBuilder:
-    | import("../../types/advanced-types.js").TypeBuilderLike
-    | undefined;
   responseBuilder:
     | import("../../types/advanced-types.js").TypeBuilderLike
     | undefined;
@@ -119,11 +108,6 @@ export class RouteCreator {
    * @returns {RouteCreator}
    */
   body(builder: import("../../index").TypeBuilderLike): RouteCreator;
-  /**
-   * @param {import("../../index").TypeBuilderLike} builder
-   * @returns {RouteCreator}
-   */
-  files(builder: import("../../index").TypeBuilderLike): RouteCreator;
   /**
    * @param {import("../../index").TypeBuilderLike} builder
    * @returns {RouteCreator}