Feat: deep check for unsupported JSON schema

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Version 20
 
+### v20.15.0
+
+- Feat: warn about potentially unserializable schema used for JSON operating endpoints:
+  - This version will warn you if you're using a schema that might not work in request or response, in particular:
+    - Generally unserializable objects: `z.map()`, `z.set()`, `z.bigint()`;
+    - JSON incompatible entities: `z.never()`, `z.void()`, `z.promise()`, `z.symbol()`, `z.nan()`;
+    - Non-revivable in request: `z.date()`;
+    - Incorrectly used in request: `ez.dateOut()`;
+    - Incorrectly used in response: `ez.dateIn()`, `ez.upload()`, `ez.raw()`;
+  - The feature suggested by [@t1nky](https://github.com/t1nky).
+
 ### v20.14.3
 
 - Fixed: missing export of `testMiddleware`:

README.md

@@ -83,6 +83,7 @@ Therefore, many basic tasks can be accomplished faster and easier, in particular
 
 These people contributed to the improvement of the library by reporting bugs, making changes and suggesting ideas:
 
+[<img src="https://github.com/t1nky.png" alt="@t1nky" width="50px" />](https://github.com/t1nky)
 [<img src="https://github.com/Tomtec331.png" alt="@Tomtec331" width="50px" />](https://github.com/Tomtec331)
 [<img src="https://github.com/williamgcampbell.png" alt="@williamgcampbell" width="50px" />](https://github.com/williamgcampbell)
 [<img src="https://github.com/rottmann.png" alt="@rottmann" width="50px" />](https://github.com/rottmann)

example/example.documentation.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Example API
-  version: 20.14.3
+  version: 20.15.0-beta.2
 paths:
   /v1/user/retrieve:
     get:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-zod-api",
-  "version": "20.14.3",
+  "version": "20.15.0-beta.2",
   "description": "A Typescript library to help you get an API server up and running with I/O schema validation and custom middlewares in minutes.",
   "license": "MIT",
   "repository": {

src/deep-checks.ts

@@ -1,7 +1,12 @@
+import { fail } from "node:assert/strict";
 import { z } from "zod";
 import { EmptyObject } from "./common-helpers";
+import { ezDateInBrand } from "./date-in-schema";
+import { ezDateOutBrand } from "./date-out-schema";
+import { ezFileBrand } from "./file-schema";
 import { IOSchema } from "./io-schema";
 import { metaSymbol } from "./metadata";
+import { ProprietaryBrand } from "./proprietary-schemas";
 import { ezRawBrand } from "./raw-schema";
 import { HandlingRules, NextHandlerInc, SchemaHandler } from "./schema-walker";
 import { ezUploadBrand } from "./upload-schema";
@@ -21,30 +26,38 @@ const onIntersection: Check = (
   { next },
 ) => [_def.left, _def.right].some(next);
 
-const onElective: Check = (
-  schema: z.ZodOptional<z.ZodTypeAny> | z.ZodNullable<z.ZodTypeAny>,
+const onWrapped: Check = (
+  schema:
+    | z.ZodOptional<z.ZodTypeAny>
+    | z.ZodNullable<z.ZodTypeAny>
+    | z.ZodReadonly<z.ZodTypeAny>
+    | z.ZodBranded<z.ZodTypeAny, string | number | symbol>,
   { next },
 ) => next(schema.unwrap());
 
-const checks: HandlingRules<boolean, EmptyObject, z.ZodFirstPartyTypeKind> = {
+const ioChecks: HandlingRules<boolean, EmptyObject, z.ZodFirstPartyTypeKind> = {
   ZodObject: ({ shape }: z.ZodObject<z.ZodRawShape>, { next }) =>
     Object.values(shape).some(next),
   ZodUnion: onSomeUnion,
   ZodDiscriminatedUnion: onSomeUnion,
   ZodIntersection: onIntersection,
   ZodEffects: (schema: z.ZodEffects<z.ZodTypeAny>, { next }) =>
     next(schema.innerType()),
-  ZodOptional: onElective,
-  ZodNullable: onElective,
+  ZodOptional: onWrapped,
+  ZodNullable: onWrapped,
   ZodRecord: ({ valueSchema }: z.ZodRecord, { next }) => next(valueSchema),
   ZodArray: ({ element }: z.ZodArray<z.ZodTypeAny>, { next }) => next(element),
   ZodDefault: ({ _def }: z.ZodDefault<z.ZodTypeAny>, { next }) =>
     next(_def.innerType),
 };
 
 interface NestedSchemaLookupProps {
-  condition: (schema: z.ZodTypeAny) => boolean;
-  rules?: HandlingRules<boolean>;
+  condition?: (schema: z.ZodTypeAny) => boolean;
+  rules?: HandlingRules<
+    boolean,
+    EmptyObject,
+    z.ZodFirstPartyTypeKind | ProprietaryBrand
+  >;
   maxDepth?: number;
   depth?: number;
 }
@@ -54,17 +67,16 @@ export const hasNestedSchema = (
   subject: z.ZodTypeAny,
   {
     condition,
-    rules = checks,
+    rules = ioChecks,
     depth = 1,
     maxDepth = Number.POSITIVE_INFINITY,
   }: NestedSchemaLookupProps,
 ): boolean => {
-  if (condition(subject)) {
-    return true;
-  }
+  if (condition?.(subject)) return true;
   const handler =
     depth < maxDepth
-      ? rules[subject._def.typeName as keyof typeof rules]
+      ? rules[subject._def[metaSymbol]?.brand as keyof typeof rules] ||
+        rules[subject._def.typeName as keyof typeof rules]
       : undefined;
   if (handler) {
     return handler(subject, {
@@ -90,3 +102,42 @@ export const hasRaw = (subject: IOSchema) =>
     condition: (schema) => schema._def[metaSymbol]?.brand === ezRawBrand,
     maxDepth: 3,
   });
+
+/** @throws AssertionError with incompatible schema constructor */
+export const assertJsonCompatible = (subject: IOSchema, dir: "in" | "out") => {
+  const lazies = new WeakSet<z.ZodLazy<z.ZodTypeAny>>();
+  return hasNestedSchema(subject, {
+    maxDepth: 300,
+    rules: {
+      ...ioChecks,
+      ZodBranded: onWrapped,
+      ZodReadonly: onWrapped,
+      ZodCatch: ({ _def: { innerType } }: z.ZodCatch<z.ZodTypeAny>, { next }) =>
+        next(innerType),
+      ZodPipeline: (
+        { _def }: z.ZodPipeline<z.ZodTypeAny, z.ZodTypeAny>,
+        { next },
+      ) => next(_def[dir]),
+      ZodLazy: (lazy: z.ZodLazy<z.ZodTypeAny>, { next }) =>
+        lazies.has(lazy) ? false : lazies.add(lazy) && next(lazy.schema),
+      ZodTuple: ({ items, _def: { rest } }: z.AnyZodTuple, { next }) =>
+        [...items].concat(rest ?? []).some(next),
+      ZodEffects: { out: undefined, in: ioChecks.ZodEffects }[dir],
+      ZodNaN: () => fail("z.nan()"),
+      ZodSymbol: () => fail("z.symbol()"),
+      ZodFunction: () => fail("z.function()"),
+      ZodMap: () => fail("z.map()"),
+      ZodSet: () => fail("z.set()"),
+      ZodBigInt: () => fail("z.bigint()"),
+      ZodVoid: () => fail("z.void()"),
+      ZodPromise: () => fail("z.promise()"),
+      ZodNever: () => fail("z.never()"),
+      ZodDate: () => dir === "in" && fail("z.date()"),
+      [ezDateOutBrand]: () => dir === "in" && fail("ez.dateOut()"),
+      [ezDateInBrand]: () => dir === "out" && fail("ez.dateIn()"),
+      [ezRawBrand]: () => dir === "out" && fail("ez.raw()"),
+      [ezUploadBrand]: () => dir === "out" && fail("ez.upload()"),
+      [ezFileBrand]: () => false,
+    },
+  });
+};

src/routing.ts

@@ -1,8 +1,10 @@
 import { IRouter, RequestHandler } from "express";
 import { CommonConfig } from "./config-type";
-import { ContentType } from "./content-type";
+import { ContentType, contentTypes } from "./content-type";
+import { assertJsonCompatible } from "./deep-checks";
 import { DependsOnMethod } from "./depends-on-method";
 import { AbstractEndpoint } from "./endpoint";
+import { ActualLogger } from "./logger-helpers";
 import { walkRouting } from "./routing-walker";
 import { ServeStatic } from "./serve-static";
 import { ChildLoggerExtractor } from "./server-helpers";
@@ -15,24 +17,53 @@ export type Parsers = Record<ContentType, RequestHandler[]>;
 
 export const initRouting = ({
   app,
+  rootLogger,
   getChildLogger,
   config,
   routing,
   parsers,
 }: {
   app: IRouter;
+  rootLogger: ActualLogger;
   getChildLogger: ChildLoggerExtractor;
   config: CommonConfig;
   routing: Routing;
   parsers?: Parsers;
-}) =>
+}) => {
+  const verified = new WeakSet<AbstractEndpoint>();
   walkRouting({
     routing,
     hasCors: !!config.cors,
     onEndpoint: (endpoint, path, method, siblingMethods) => {
+      const requestType = endpoint.getRequestType();
+      if (!verified.has(endpoint)) {
+        if (requestType === "json") {
+          try {
+            assertJsonCompatible(endpoint.getSchema("input"), "in");
+          } catch (reason) {
+            rootLogger.warn(
+              "The final input schema of the endpoint contains an unsupported JSON payload type.",
+              { path, method, reason },
+            );
+          }
+        }
+        for (const variant of ["positive", "negative"] as const) {
+          if (endpoint.getMimeTypes(variant).includes(contentTypes.json)) {
+            try {
+              assertJsonCompatible(endpoint.getSchema(variant), "out");
+            } catch (reason) {
+              rootLogger.warn(
+                `The final ${variant} response schema of the endpoint contains an unsupported JSON payload type.`,
+                { path, method, reason },
+              );
+            }
+          }
+        }
+        verified.add(endpoint);
+      }
       app[method](
         path,
-        ...(parsers?.[endpoint.getRequestType()] || []),
+        ...(parsers?.[requestType] || []),
         async (request, response) =>
           endpoint.execute({
             request,
@@ -47,3 +78,4 @@ export const initRouting = ({
       app.use(path, handler);
     },
   });
+};

src/server.ts

@@ -47,6 +47,7 @@ export const attachRouting = (config: AppConfig, routing: Routing) => {
     makeCommonEntities(config);
   initRouting({
     app: config.app.use(loggingMiddleware),
+    rootLogger,
     routing,
     getChildLogger,
     config,
@@ -90,7 +91,7 @@ export const createServer = async (config: ServerConfig, routing: Routing) => {
       getChildLogger,
     });
   }
-  initRouting({ app, routing, getChildLogger, config, parsers });
+  initRouting({ app, routing, rootLogger, getChildLogger, config, parsers });
   app.use(parserFailureHandler, notFoundHandler);
 
   const starter = <T extends http.Server | https.Server>(

tests/bench/experiment.bench.ts

@@ -1,17 +1,18 @@
 import { bench } from "vitest";
-import { keys, keysIn } from "ramda";
-import { defaultStatusCodes } from "../../src/api-response";
 
 describe("Experiment %s", () => {
-  bench("Object.keys()", () => {
-    Object.keys(defaultStatusCodes);
-  });
+  const map = new WeakMap();
+  const set = new WeakSet();
+  const obj = {};
 
-  bench("R.keys()", () => {
-    keys(defaultStatusCodes);
+  bench("WeakMap.has()", () => {
+    map.has({});
   });
 
-  bench("R.keysIn()", () => {
-    keysIn(defaultStatusCodes);
+  bench("WeakSet.has()", () => {
+    set.has({});
   });
+
+  bench("control: in", () => void ("test" in obj));
+  bench("control: hasOwn", () => void Object.hasOwn(obj, "test"));
 });

tests/unit/documentation.spec.ts

@@ -556,12 +556,15 @@ describe("Documentation", () => {
     test.each([
       z.undefined(),
       z.map(z.any(), z.any()),
+      z.set(z.any()),
       z.function(),
       z.promise(z.any()),
+      z.nan(),
+      z.symbol(),
       z.unknown(),
       z.never(),
       z.void(),
-    ])("should throw on unsupported types", (zodType) => {
+    ])("should throw on unsupported types %#", (zodType) => {
       expect(
         () =>
           new Documentation({