@jskit-ai/kernel 0.1.55 → 0.1.56

package/server/http/lib/routeValidator.test.js

@@ -1,57 +1,105 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createSchema } from "json-rest-schema";
 
 import { createRouter } from "./router.js";
 import { compileRouteValidator, defineRouteValidator, resolveRouteValidatorOptions } from "./routeValidator.js";
 
+function stripJsonRestTransportExtensions(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stripJsonRestTransportExtensions(entry));
+  }
+
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+
+  const sanitized = {};
+
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "x-json-rest-schema") {
+      continue;
+    }
+
+    sanitized[key] = stripJsonRestTransportExtensions(entry);
+  }
+
+  return sanitized;
+}
+
+function toFastifySchema(schema, mode) {
+  return stripJsonRestTransportExtensions(schema.toJsonSchema({ mode }));
+}
+
+function createMockJsonRestSchema() {
+  return createSchema({
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: 160,
+      messages: {
+        minLength: "Name is required."
+      }
+    }
+  });
+}
+
 test("defineRouteValidator compiles body/query/params and maps query schema to querystring", () => {
-  const bodySchema = {
-    type: "object"
-  };
-  const querySchema = {
-    type: "object"
-  };
-  const paramsSchema = {
-    type: "object"
-  };
+  const bodySchema = createSchema({
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1
+    }
+  });
+  const querySchema = createSchema({
+    search: {
+      type: "string",
+      required: false,
+      minLength: 1
+    }
+  });
+  const paramsSchema = createSchema({
+    contactId: {
+      type: "string",
+      required: true,
+      minLength: 1
+    }
+  });
+  const responseBodySchema = createSchema({
+    ok: {
+      type: "boolean",
+      required: true
+    }
+  });
   const responseSchema = {
     200: {
-      schema: {
-        type: "object"
-      }
+      schema: responseBodySchema
     }
   };
   const headersSchema = {
     type: "object"
   };
 
-  const normalizeBody = (body) => body;
-  const normalizeQuery = (query) => query;
-  const normalizeParams = (params) => params;
-
   const validator = defineRouteValidator({
     meta: {
       tags: ["contacts", "intake"],
       summary: "Create contact intake"
     },
-    bodyValidator: {
-      schema: bodySchema,
-      normalize: normalizeBody
+    body: {
+      schema: bodySchema
     },
-    queryValidator: {
-      schema: querySchema,
-      normalize: normalizeQuery
+    query: {
+      schema: querySchema
     },
-    paramsValidator: {
+    params: {
       schema: paramsSchema
     },
-    responseValidators: responseSchema,
+    responses: responseSchema,
     advanced: {
       fastifySchema: {
         headers: headersSchema
-      },
-      jskitInput: {
-        params: normalizeParams
       }
     }
   });
@@ -61,62 +109,73 @@ test("defineRouteValidator compiles body/query/params and maps query schema to q
   assert.deepEqual(compiled.schema, {
     tags: ["contacts", "intake"],
     summary: "Create contact intake",
-    body: bodySchema,
-    querystring: querySchema,
-    params: paramsSchema,
+    body: toFastifySchema(bodySchema, "patch"),
+    querystring: toFastifySchema(querySchema, "patch"),
+    params: toFastifySchema(paramsSchema, "patch"),
     response: {
-      200: {
-        type: "object"
-      }
+      200: toFastifySchema(responseBodySchema, "replace")
     },
     headers: headersSchema
   });
-  assert.equal(compiled.input.body, normalizeBody);
-  assert.equal(compiled.input.query, normalizeQuery);
-  assert.equal(compiled.input.params, normalizeParams);
+  assert.equal(typeof compiled.input.body, "function");
+  assert.equal(typeof compiled.input.query, "function");
+  assert.equal(typeof compiled.input.params, "function");
+  assert.deepEqual(compiled.input.body({
+    name: "  Acme  "
+  }), {
+    name: "Acme"
+  });
 });
 
-test("compileRouteValidator accepts plain validator objects", () => {
-  const querySchema = {
-    type: "object"
-  };
-  const normalizeQuery = (query) => ({
-    dryRun: Boolean(query?.dryRun)
+test("compileRouteValidator accepts json-rest-schema definitions", () => {
+  const querySchema = createSchema({
+    search: {
+      type: "string",
+      required: false,
+      minLength: 1
+    }
   });
 
   const compiled = compileRouteValidator({
-    queryValidator: {
-      schema: querySchema,
-      normalize: normalizeQuery
+    query: {
+      schema: querySchema
     }
   });
 
   assert.deepEqual(compiled.schema, {
-    querystring: querySchema
+    querystring: toFastifySchema(querySchema, "patch")
   });
-  assert.equal(compiled.input.query, normalizeQuery);
+  assert.equal(typeof compiled.input.query, "function");
 });
 
-test("compileRouteValidator creates pass-through request.input transforms for schema-only params and query", () => {
-  const querySchema = {
-    type: "object"
-  };
-  const paramsSchema = {
-    type: "object"
-  };
+test("compileRouteValidator creates request.input transforms for schema-only params and query", () => {
+  const querySchema = createSchema({
+    workspaceSlug: {
+      type: "string",
+      required: false,
+      minLength: 1
+    }
+  });
+  const paramsSchema = createSchema({
+    workspaceSlug: {
+      type: "string",
+      required: true,
+      minLength: 1
+    }
+  });
 
   const compiled = compileRouteValidator({
-    queryValidator: {
+    query: {
       schema: querySchema
     },
-    paramsValidator: {
+    params: {
       schema: paramsSchema
     }
   });
 
   assert.deepEqual(compiled.schema, {
-    querystring: querySchema,
-    params: paramsSchema
+    querystring: toFastifySchema(querySchema, "patch"),
+    params: toFastifySchema(paramsSchema, "patch")
   });
   assert.equal(typeof compiled.input.query, "function");
   assert.equal(typeof compiled.input.params, "function");
@@ -124,202 +183,111 @@ test("compileRouteValidator creates pass-through request.input transforms for sc
   assert.deepEqual(compiled.input.params({ workspaceSlug: "acme" }), { workspaceSlug: "acme" });
 });
 
-test("compileRouteValidator accepts response validator objects and extracts only response schemas", () => {
-  const responseBodySchema = {
-    type: "object"
-  };
-  const normalizeOutput = (payload) => ({
-    ...payload,
-    normalized: true
+test("compileRouteValidator accepts response schema definitions and extracts only response schemas", () => {
+  const responseBodySchema = createSchema({
+    ok: {
+      type: "boolean",
+      required: true
+    }
   });
 
   const compiled = compileRouteValidator({
-    responseValidators: {
+    responses: {
       200: {
-        schema: responseBodySchema,
-        normalize: normalizeOutput
+        schema: responseBodySchema
       },
       400: {
-        schema: {
-          type: "object"
-        }
+        schema: createSchema({
+          ok: {
+            type: "boolean",
+            required: true
+          }
+        })
       }
     }
   });
 
   assert.deepEqual(compiled.schema, {
     response: {
-      200: responseBodySchema,
-      400: {
-        type: "object"
-      }
+      200: toFastifySchema(responseBodySchema, "replace"),
+      400: toFastifySchema(createSchema({
+        ok: {
+          type: "boolean",
+          required: true
+        }
+      }), "replace")
     }
   });
-  assert.equal(Object.prototype.hasOwnProperty.call(compiled, "output"), false);
+  assert.equal(Object.hasOwn(compiled, "output"), false);
 });
 
-test("compileRouteValidator merges query validator arrays automatically", () => {
-  const paginationQuery = {
-    schema: {
-      type: "object",
-      properties: {
-        cursor: {
-          type: "string"
-        }
-      },
-      additionalProperties: false
-    }
-  };
-  const searchQuery = {
-    schema: {
-      type: "object",
-      properties: {
-        search: {
-          type: "string"
-        }
-      },
-      additionalProperties: false
-    }
-  };
-
+test("compileRouteValidator turns json-rest-schema validators into transport schema plus input normalization", () => {
+  const bodySchema = createMockJsonRestSchema();
   const compiled = compileRouteValidator({
-    queryValidator: [paginationQuery, searchQuery]
+    body: {
+      schema: bodySchema,
+      mode: "patch"
+    }
   });
 
   assert.deepEqual(compiled.schema, {
-    querystring: {
-      type: "object",
-      properties: {
-        cursor: {
-          type: "string"
-        },
-        search: {
-          type: "string"
-        }
-      },
-      required: ["cursor", "search"],
-      additionalProperties: false
-    }
+    body: toFastifySchema(bodySchema, "patch")
   });
-});
 
-test("compileRouteValidator merges params validator arrays automatically", () => {
-  const workspaceSlugParams = {
-    schema: {
-      type: "object",
-      properties: {
-        workspaceSlug: {
-          type: "string"
-        }
-      },
-      required: ["workspaceSlug"],
-      additionalProperties: false
-    }
-  };
-  const inviteIdParams = {
-    schema: {
-      type: "object",
-      properties: {
-        inviteId: {
-          type: "string"
-        }
-      },
-      required: ["inviteId"],
-      additionalProperties: false
-    }
-  };
+  const normalized = compiled.input.body({
+    name: "  Acme  "
+  });
+  assert.deepEqual(normalized, {
+    name: "Acme"
+  });
+});
 
+test("compileRouteValidator surfaces shared schema validation errors with HTTP 400 metadata", () => {
+  const bodySchema = createMockJsonRestSchema();
   const compiled = compileRouteValidator({
-    paramsValidator: [workspaceSlugParams, inviteIdParams]
+    body: {
+      schema: bodySchema,
+      mode: "patch"
+    }
   });
 
-  assert.deepEqual(compiled.schema, {
-    params: {
-      type: "object",
-      properties: {
-        workspaceSlug: {
-          type: "string"
-        },
-        inviteId: {
-          type: "string"
-        }
-      },
-      required: ["workspaceSlug", "inviteId"],
-      additionalProperties: false
+  assert.throws(
+    () => compiled.input.body({ name: "" }),
+    (error) => {
+      assert.equal(error?.statusCode, 400);
+      assert.deepEqual(error?.details?.fieldErrors, {
+        name: "Name is required."
+      });
+      return true;
     }
-  });
+  );
 });
 
-test("compileRouteValidator composes multiple query normalizers in validator arrays", () => {
-  const compiled = compileRouteValidator({
-    queryValidator: [
-      {
-        schema: {
-          type: "object",
-          properties: {
+test("compileRouteValidator rejects validator arrays", () => {
+  assert.throws(
+    () => compileRouteValidator({
+      query: [
+        {
+          schema: createSchema({
             cursor: {
-              type: "string"
-            }
-          },
-          additionalProperties: false
-        },
-        normalize(query = {}) {
-          return {
-            cursor: String(query.cursor || "").trim()
-          };
-        }
-      },
-      {
-        schema: {
-          type: "object",
-          properties: {
-            search: {
-              type: "string"
+              type: "string",
+              required: false
             }
-          },
-          additionalProperties: false
-        },
-        normalize(query = {}) {
-          return {
-            search: String(query.search || "").trim().toLowerCase()
-          };
+          })
         }
-      }
-    ]
-  });
-
-  assert.deepEqual(compiled.input.query({ cursor: " 100 ", search: " ACME " }), {
-    cursor: "100",
-    search: "acme"
-  });
-});
-
-test("resolveRouteValidatorOptions ignores legacy schema/input definitions", () => {
-  const resolved = resolveRouteValidatorOptions({
-    method: "POST",
-    path: "/contacts",
-    options: {
-      schema: {
-        bodyValidator: {}
-      },
-      input: {
-        body: () => ({})
-      },
-      middleware: ["api"]
-    }
-  });
-
-  assert.equal(Object.prototype.hasOwnProperty.call(resolved, "schema"), false);
-  assert.equal(Object.prototype.hasOwnProperty.call(resolved, "input"), false);
-  assert.deepEqual(resolved.middleware, ["api"]);
+      ]
+    }),
+    /route validator\.query must be a schema definition object/
+  );
 });
 
 test("resolveRouteValidatorOptions supports inline validator shape without wrapper", () => {
-  const bodySchema = {
-    type: "object"
-  };
-  const normalizeBody = (body) => ({
-    name: String(body?.name || "").trim()
+  const bodySchema = createSchema({
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1
+    }
   });
 
   const resolved = resolveRouteValidatorOptions({
@@ -330,9 +298,8 @@ test("resolveRouteValidatorOptions supports inline validator shape without wrapp
         tags: ["contacts"],
         summary: "Create contact"
       },
-      bodyValidator: {
-        schema: bodySchema,
-        normalize: normalizeBody
+      body: {
+        schema: bodySchema
       },
       middleware: ["api"]
     }
@@ -341,37 +308,73 @@ test("resolveRouteValidatorOptions supports inline validator shape without wrapp
   assert.deepEqual(resolved.schema, {
     tags: ["contacts"],
     summary: "Create contact",
-    body: bodySchema
+    body: toFastifySchema(bodySchema, "patch")
+  });
+  assert.equal(typeof resolved.input.body, "function");
+  assert.deepEqual(resolved.input.body({
+    name: "  Ada  "
+  }), {
+    name: "Ada"
   });
-  assert.equal(resolved.input.body, normalizeBody);
   assert.deepEqual(resolved.middleware, ["api"]);
 });
 
-test("resolveRouteValidatorOptions ignores validator wrapper", () => {
-  const resolved = resolveRouteValidatorOptions({
-    method: "POST",
-    path: "/contacts",
-    options: {
-      validator: defineRouteValidator({}),
-      middleware: ["api"]
-    }
-  });
+test("resolveRouteValidatorOptions rejects schema/input definitions", () => {
+  assert.throws(
+    () => resolveRouteValidatorOptions({
+      method: "POST",
+      path: "/contacts",
+      options: {
+        schema: {
+          body: {}
+        },
+        input: {
+          body: () => ({})
+        },
+        middleware: ["api"]
+      }
+    }),
+    /uses unsupported validator options: schema, input/
+  );
+});
 
-  assert.equal(Object.prototype.hasOwnProperty.call(resolved, "validator"), false);
-  assert.deepEqual(resolved.middleware, ["api"]);
+test("resolveRouteValidatorOptions rejects validator wrapper", () => {
+  assert.throws(
+    () => resolveRouteValidatorOptions({
+      method: "POST",
+      path: "/contacts",
+      options: {
+        validator: defineRouteValidator({}),
+        middleware: ["api"]
+      }
+    }),
+    /uses unsupported validator options: validator/
+  );
 });
 
-test("defineRouteValidator rejects unsupported advanced.jskitInput keys", () => {
+test("defineRouteValidator rejects unsupported advanced.jskitInput", () => {
   assert.throws(
     () =>
       defineRouteValidator({
         advanced: {
-          jskitInput: {
-            headers: () => ({})
+          jskitInput: {}
+        }
+      }),
+    /advanced\.jskitInput is not supported/
+  );
+});
+
+test("defineRouteValidator rejects unsupported top-level keys generically", () => {
+  assert.throws(
+    () =>
+      defineRouteValidator({
+        unsupportedContract: {
+          schema: {
+            type: "object"
           }
         }
       }),
-    /advanced\.jskitInput\.headers is not supported/
+    /defineRouteValidator\(\)\.unsupportedContract is not supported/
   );
 });
 
@@ -397,56 +400,55 @@ test("defineRouteValidator validates meta fields", () => {
   );
 });
 
-test("HttpRouter.register ignores validator wrapper options", () => {
+test("HttpRouter.register rejects validator wrapper options", () => {
   const router = createRouter();
-  router.register(
-    "POST",
-    "/contacts",
-    {
-      validator: defineRouteValidator({})
-    },
-    async () => {}
+  assert.throws(
+    () => router.register(
+      "POST",
+      "/contacts",
+      {
+        validator: defineRouteValidator({})
+      },
+      async () => {}
+    ),
+    /uses unsupported validator options: validator/
   );
-
-  const [route] = router.list();
-  assert.equal(route.schema, undefined);
-  assert.equal(route.input, null);
 });
 
-test("HttpRouter.register ignores compiled legacy-style route options", () => {
+test("HttpRouter.register rejects compiled route option payloads", () => {
   const router = createRouter();
-  const querySchema = {
-    type: "object"
-  };
-  const normalizeQuery = (query) => ({
-    dryRun: query?.dryRun === true
+  const querySchema = createSchema({
+    dryRun: {
+      type: "boolean",
+      required: false,
+      strictBoolean: true
+    }
   });
 
   const validator = defineRouteValidator({
-    queryValidator: {
-      schema: querySchema,
-      normalize: normalizeQuery
+    query: {
+      schema: querySchema
     }
   });
 
-  router.get(
-    "/contacts",
-    validator.toRouteOptions(),
-    async () => {}
+  assert.throws(
+    () => router.get(
+      "/contacts",
+      validator.toRouteOptions(),
+      async () => {}
+    ),
+    /uses unsupported validator options: schema, input/
   );
-
-  const [route] = router.list();
-  assert.equal(route.schema, undefined);
-  assert.equal(route.input, null);
 });
 
 test("HttpRouter.register accepts inline validator shape directly", () => {
   const router = createRouter();
-  const querySchema = {
-    type: "object"
-  };
-  const normalizeQuery = (query) => ({
-    dryRun: query?.dryRun === true
+  const querySchema = createSchema({
+    dryRun: {
+      type: "boolean",
+      required: false,
+      strictBoolean: true
+    }
   });
 
   router.get(
@@ -456,9 +458,8 @@ test("HttpRouter.register accepts inline validator shape directly", () => {
         tags: ["contacts"],
         summary: "List contacts"
       },
-      queryValidator: {
-        schema: querySchema,
-        normalize: normalizeQuery
+      query: {
+        schema: querySchema
       }
     },
     async () => {}
@@ -468,7 +469,113 @@ test("HttpRouter.register accepts inline validator shape directly", () => {
   assert.deepEqual(route.schema, {
     tags: ["contacts"],
     summary: "List contacts",
-    querystring: querySchema
+    querystring: toFastifySchema(querySchema, "patch")
+  });
+  assert.equal(typeof route.input.query, "function");
+  assert.deepEqual(route.input.query({
+    dryRun: true
+  }), {
+    dryRun: true
+  });
+});
+
+test("HttpRouter.register accepts explicit transport metadata and output transform", () => {
+  const router = createRouter();
+  const output = (payload) => ({
+    data: payload
+  });
+  const error = (currentError) => ({
+    errors: [{
+      title: currentError.message
+    }]
   });
-  assert.equal(route.input.query, normalizeQuery);
+
+  router.get(
+    "/contacts",
+    {
+      transport: {
+        kind: "jsonapi-resource",
+        contentType: "application/vnd.api+json",
+        request: {
+          body(body) {
+            return body?.data?.attributes || {};
+          }
+        },
+        error
+      },
+      output
+    },
+    async () => {}
+  );
+
+  const [route] = router.list();
+  assert.equal(route.transport.kind, "jsonapi-resource");
+  assert.equal(route.transport.contentType, "application/vnd.api+json");
+  assert.equal(typeof route.transport.request.body, "function");
+  assert.equal(route.transport.error, error);
+  assert.equal(route.output, output);
+});
+
+test("HttpRouter.register rejects invalid transport definitions and output transforms", () => {
+  const router = createRouter();
+
+  assert.throws(
+    () => router.get(
+      "/contacts",
+      {
+        transport: {
+          kind: "weird"
+        }
+      },
+      async () => {}
+    ),
+    /transport\.kind must be one of: command, jsonapi-resource/
+  );
+
+  assert.throws(
+    () => router.get(
+      "/contacts",
+      {
+        output: {
+          mode: "unsupported"
+        }
+      },
+      async () => {}
+    ),
+    /output must be a function/
+  );
+});
+
+test("compileRouteValidator strips json-rest transport metadata before Fastify handoff", () => {
+  const nestedSchema = createSchema({
+    profile: {
+      type: "object",
+      required: false,
+      schema: createSchema({
+        email: {
+          type: "string",
+          required: false,
+          minLength: 3,
+          format: "email"
+        }
+      }),
+      additionalProperties: true
+    }
+  });
+
+  const compiled = compileRouteValidator({
+    body: {
+      schema: nestedSchema
+    },
+    responses: {
+      200: {
+        schema: nestedSchema,
+        mode: "replace"
+      }
+    }
+  });
+
+  assert.equal(JSON.stringify(compiled.schema).includes("x-json-rest-schema"), false);
+  assert.deepEqual(compiled.schema.body, toFastifySchema(nestedSchema, "patch"));
+  assert.deepEqual(compiled.schema.response[200], toFastifySchema(nestedSchema, "replace"));
 });