v0.3.0 documentation

[diego-aquino]

• Document API changes introduced in v0.3.0
  • README.md
  • Code documentation with JSDoc
• Add examples to headline links to README
• Change examples in README to follow the new strict JSON validation.

[diego-aquino]

Migrating from v0.2 to v0.3

Strict JSON validation

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

v0.3.0 now adds strict JSON validation to interceptor declarations. Unfortunately, it is no longer possible to declare
body types using raw TypeScript interface's, because they do not have implicit index signatures as type's do. To declare entities used in JSON bodies, you can now use the utility type JSONValue, exported by zimic, .

Refactoring body interfaces to types using JSONValue

If you were using interfaces to declare body types, follow the steps below. If you are already using types, skip to step 2.

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 JSON body in HTTP interceptor schemas, consider using JSONValue to make sure the type can
   be represented as JSON. This is not required, although it provides more type safety to your code. Following the
   example of step 1:

   import type { JSONValue } from 'zimic';
   
   // Now checked that it is compatible with JSON
   type User = JSONValue<{
     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, JSONValue
     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. 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; becomes `string` when serialized
     }
     
     type UserResponse = JSONSerialized<User>; // Converts `birthDate` from `Date` to `string`
     
     const interceptor = createHttpInterceptor<{
       GET: {
         response: {
           200: { body: UserResponse[] }; // No error!
         };
       };
     }>({
       worker,
       baseURL: 'http://localhost:3000',
     });

HTTP types exports moved from zimic/interceptor to zimic

As part of Zimic's export improvements, generic HTTP types are now exported directly from zimic, as opposed to
zimic/interceptor. This is more appropriate because those types are not specific to Zimic interceptors. No behavior
changes were added to the types moved, so migrating means just renaming and importing them from zimic directly.

Previously exported from zimic/interceptor:	Equivalent now exported from zimic:
HttpInterceptorMethod	HttpMethod
HttpInterceptorMethodSchema	HttpServiceMethodSchema
HttpInterceptorPathSchema	HttpServiceMethodsSchema
HttpInterceptorRequestSchema	HttpServiceRequestSchema
HttpInterceptorResponseSchema	HttpServiceResponseSchema
HttpInterceptorResponseSchemaByStatusCode	HttpServiceResponseSchemaByStatusCode
HttpInterceptorResponseSchemaStatusCode	HttpServiceResponseSchemaStatusCode
HttpInterceptorSchemaMethod	HttpServiceSchemaMethod
HttpInterceptorSchemaPath	HttpServiceSchemaPath
LiteralHttpInterceptorSchemaPath	LiteralHttpServiceSchemaPath
NonLiteralHttpInterceptorSchemaPath	NonLiteralHttpServiceSchemaPath
HttpInterceptorSearchParamsSchema	HttpSearchParamsSchema
HttpInterceptorBodySchema	HttpBody
HttpInterceptorSchema	HttpServiceSchema
HttpInterceptorSchema.Root	HttpSchema.Paths
HttpInterceptorSchema.Path	HttpSchema.Methods
HttpInterceptorSchema.Method	HttpSchema.Method
HttpInterceptorSchema.Request	HttpSchema.Request
HttpInterceptorSchema.ResponseByStatusCode	HttpSchema.ResponseByStatusCode
HttpInterceptorSchema.Response	HttpSchema.Response
HttpInterceptorSchema.Headers	HttpSchema.Headers
HttpInterceptorSchema.SearchParams	HttpSchema.SearchParams
HttpInterceptorSchema.RequestBody	JSONValue
HttpInterceptorSchema.ResponseBody	JSONValue

Tip

HttpSchema is a namespace, so it is imported as import { HttpSchema } from 'zimic';. For example:

import type { HttpSchema } from 'zimic';

type UserListSearchParams = HttpSchema.SearchParams<{
  name?: string;
  orderBy?: string[];
}>;