HTTP interceptor strict JSON validation

[diego-aquino]

As of v0.2.x, JSON bodies are not completely statically validated. This allows defining bodies using non-JSON values, such as Date and Error.

This issue means to add strict JSON validation to interceptor declarations. Unfortunately, it won't be possible to declare body types using raw TypeScript interface's, because they do not have automatic index signatures as type's. See microsoft/TypeScript#15300 for more information.

microsoft/TypeScript#1897 proposes a native json type, which might help in the future. Right now, though, the interface vs type problem seems unsolvable natively.

[diego-aquino]

Migration guide

In order to keep compatibility with client code bases with minimal changes, I'm proposing a new utility typed exported by zimic called JSONCompatible. In code bases using interfaces, the migration workflow is as follows:

1. For each interface used as body in HTTP interceptor schemas, refactor them to use type. For example:

   interface User {
     id: string;
     name: string;
   }
   
   const interceptor = createHttpInterceptor<{
     GET: {
       response: {
         // shows an error because interfaces do not have index signatures by default
         200: { body: User[] };
       };
     };
   }>({
     worker,
     baseURL: 'http://localhost:3000',
   });

   should be refactored to:

   // refactored from interface to type
   type User = {
     id: string;
     name: string;
   };
   
   const interceptor = createHttpInterceptor<{
     GET: {
       response: {
         200: { body: User[] }; // no error now!
       };
     };
   }>({
     worker,
     baseURL: 'http://localhost:3000',
   });

2. For each type used as body in HTTP interceptor schemas, consider using JSONCompatible to make sure the type can be represented as an HTTP body (e.g. is a valid JSON). This is not required, although it provides more type safety to your code. Following the example of step 1:

   import type { JSONCompatible } from 'zimic';
   
   // now checked that it is compatible with HTTP bodies
   type User = JSONCompatible<{
     id: string;
     name: string;
   }>;
   
   const interceptor = createHttpInterceptor<{
     GET: {
       response: {
         200: { body: User[] };
       };
     };
   }>({
     worker,
     baseURL: 'http://localhost:3000',
   });

   • In case your interface or type was relying on the loose JSON validation and using non-JSON properties, JSONCompatible will show type errors. This is expected because the type was in fact not JSON-compatible. To fix this problem, we recommend using another utility type exported by zimic, JSONSerialized, which transforms an object type into its equivalent when serialized as JSON and later deserialized. In this case, refactoring the original interface to type is not required. For example:

     import type { JSONSerialized } from 'zimic';
     
     // since `User` is no longer used directly in the schema,
     // declaring it as an interface or type are both valid
     interface User {
       id: string;
       name: string;
       birthDate: Date; // not a valid JSON value; actually becomes `string` when serialized
     }
     
     type UserResponse = JSONSerialized<User>;
     
     const interceptor = createHttpInterceptor<{
       GET: {
         response: {
           // converts `birthDate: Date` to `birthDate: string`
           200: { body: JSONSerialized<User>[] }; // no error!
         };
       };
     }>({
       worker,
       baseURL: 'http://localhost:3000',
     });