@jskit-ai/kernel 0.1.55 → 0.1.56

package/server/http/lib/routeValidator.js

@@ -1,125 +1,65 @@
 import { normalizeObject, normalizeText } from "../../../shared/support/normalize.js";
-import { mergeValidators } from "../../../shared/validators/mergeValidators.js";
+import {
+  normalizeSchemaDefinition,
+  resolveSchemaTransportSchemaDefinition,
+  validateSchemaPayload
+} from "../../../shared/validators/index.js";
 import { RouteDefinitionError } from "./errors.js";
 import { resolveRouteLabel } from "./routeSupport.js";
 
 const ROUTE_VALIDATOR_SYMBOL = "@jskit-ai/kernel/http/routeValidator";
+const JSON_REST_TRANSPORT_EXTENSION_KEY = "x-json-rest-schema";
 const VALIDATOR_OPTION_KEYS = Object.freeze([
   "meta",
-  "bodyValidator",
-  "queryValidator",
-  "paramsValidator",
-  "responseValidators",
+  "body",
+  "query",
+  "params",
+  "responses",
   "advanced"
 ]);
+const ADVANCED_VALIDATOR_OPTION_KEYS = Object.freeze([
+  "fastifySchema"
+]);
+const UNSUPPORTED_ROUTE_VALIDATOR_KEYS = Object.freeze([
+  "schema",
+  "input",
+  "validator"
+]);
 
-function passThroughInputSection(value) {
-  return value;
-}
-
-function normalizeOptionalValidatorTransformer(source, normalized, { context = "route validator" } = {}) {
-  if (!Object.prototype.hasOwnProperty.call(source, "normalize")) {
-    return;
-  }
-
-  const normalize = source.normalize;
-  if (normalize != null && typeof normalize !== "function") {
-    throw new RouteDefinitionError(`${context}.normalize must be a function.`);
-  }
-  if (typeof normalize === "function") {
-    normalized.normalize = normalize;
-  }
-}
-
-function normalizeSingleRouteValidator(value, { context = "route validator" } = {}) {
-  if (value == null) {
-    return Object.freeze({});
-  }
-
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new RouteDefinitionError(`${context} must be an object.`);
+function stripJsonRestTransportExtensions(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => stripJsonRestTransportExtensions(entry));
   }
 
-  const source = normalizeObject(value);
-  const normalized = {};
-
-  if (Object.prototype.hasOwnProperty.call(source, "schema")) {
-    normalized.schema = source.schema;
+  if (!value || typeof value !== "object") {
+    return value;
   }
 
-  normalizeOptionalValidatorTransformer(source, normalized, { context });
-
-  return Object.freeze(normalized);
-}
-
-function mergeNormalizedRouteValidators(validators, { context = "route validator" } = {}) {
-  return mergeValidators(validators, {
-    context,
-    allowAsyncNormalize: false,
-    createError(message) {
-      return new RouteDefinitionError(message);
-    }
-  });
-}
+  const sanitized = {};
 
-function normalizeRouteValidator(value, { context = "route validator", allowArray = false } = {}) {
-  if (value == null) {
-    return Object.freeze({});
-  }
-
-  if (Array.isArray(value)) {
-    if (!allowArray) {
-      throw new RouteDefinitionError(`${context} does not support arrays.`);
-    }
-
-    if (value.length === 0) {
-      return Object.freeze({});
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === JSON_REST_TRANSPORT_EXTENSION_KEY) {
+      continue;
     }
 
-    const validators = value.map((entry, index) => {
-      const validator = normalizeSingleRouteValidator(entry, {
-        context: `${context}[${index}]`
-      });
-
-      if (
-        !Object.prototype.hasOwnProperty.call(validator, "schema") &&
-        !Object.prototype.hasOwnProperty.call(validator, "normalize")
-      ) {
-        throw new RouteDefinitionError(`${context}[${index}] must define schema and/or normalize.`);
-      }
-
-      return validator;
-    });
-
-    return mergeNormalizedRouteValidators(validators, {
-      context
-    });
+    sanitized[key] = stripJsonRestTransportExtensions(entry);
   }
 
-  return normalizeSingleRouteValidator(value, {
-    context
-  });
+  return sanitized;
 }
 
-function normalizeResponseValidatorEntry(value, { context = "route validator response entry" } = {}) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new RouteDefinitionError(`${context} must be an object.`);
-  }
-
-  const source = normalizeObject(value);
-  const normalized = {};
-
-  if (!Object.prototype.hasOwnProperty.call(source, "schema")) {
-    throw new RouteDefinitionError(`${context}.schema is required when using a response validator object.`);
+function normalizeRouteSchemaSection(value, { context = "route section", defaultMode = "patch" } = {}) {
+  try {
+    return normalizeSchemaDefinition(value, {
+      context,
+      defaultMode
+    });
+  } catch (error) {
+    throw new RouteDefinitionError(error?.message || `${context} is invalid.`);
   }
-  normalized.schema = source.schema;
-
-  normalizeOptionalValidatorTransformer(source, normalized, { context });
-
-  return Object.freeze(normalized);
 }
 
-function normalizeResponseValidatorDefinition(value, { context = "route validator.response" } = {}) {
+function normalizeResponseDefinition(value, { context = "route responses" } = {}) {
   if (value == null) {
     return undefined;
   }
@@ -132,8 +72,24 @@ function normalizeResponseValidatorDefinition(value, { context = "route validato
   const normalized = {};
 
   for (const [statusCode, entry] of Object.entries(source)) {
-    normalized[statusCode] = normalizeResponseValidatorEntry(entry, {
-      context: `${context}.${statusCode}`
+    const entryContext = `${context}.${statusCode}`;
+    if (
+      entry &&
+      typeof entry === "object" &&
+      !Array.isArray(entry) &&
+      Object.prototype.hasOwnProperty.call(entry, "transportSchema")
+    ) {
+      normalized[statusCode] = Object.freeze({
+        transportSchema: normalizeObject(entry.transportSchema, {
+          fallback: {}
+        })
+      });
+      continue;
+    }
+
+    normalized[statusCode] = normalizeRouteSchemaSection(entry, {
+      context: entryContext,
+      defaultMode: "replace"
     });
   }
 
@@ -155,46 +111,6 @@ function normalizeAdvancedFastifySchema(value, { context = "route validator" } =
   });
 }
 
-function normalizeAdvancedJskitInput(value, { context = "route validator" } = {}) {
-  if (!Object.prototype.hasOwnProperty.call(value, "jskitInput")) {
-    return undefined;
-  }
-
-  const jskitInput = value.jskitInput;
-  if (!jskitInput || typeof jskitInput !== "object" || Array.isArray(jskitInput)) {
-    throw new RouteDefinitionError(`${context}.advanced.jskitInput must be an object.`);
-  }
-
-  const supportedKeys = new Set(["body", "query", "params"]);
-  for (const key of Object.keys(jskitInput)) {
-    if (!supportedKeys.has(key)) {
-      throw new RouteDefinitionError(
-        `${context}.advanced.jskitInput.${key} is not supported. Use body, query, or params.`
-      );
-    }
-  }
-
-  const normalized = {};
-  for (const key of ["body", "query", "params"]) {
-    if (!Object.prototype.hasOwnProperty.call(jskitInput, key)) {
-      continue;
-    }
-
-    const transform = jskitInput[key];
-    if (transform == null) {
-      continue;
-    }
-
-    if (typeof transform !== "function") {
-      throw new RouteDefinitionError(`${context}.advanced.jskitInput.${key} must be a function.`);
-    }
-
-    normalized[key] = transform;
-  }
-
-  return Object.freeze(normalized);
-}
-
 function normalizeRouteValidatorMeta(value, { context = "route validator" } = {}) {
   if (value == null) {
     return Object.freeze({});
@@ -243,32 +159,23 @@ function normalizeRouteValidatorDefinition(sourceDefinition, { context = "route
     throw new RouteDefinitionError(`${context} must be an object.`);
   }
 
-  if (Object.prototype.hasOwnProperty.call(definition, "body")) {
-    throw new RouteDefinitionError(`${context}.body is not supported. Use ${context}.bodyValidator.`);
-  }
-  if (Object.prototype.hasOwnProperty.call(definition, "query")) {
-    throw new RouteDefinitionError(`${context}.query is not supported. Use ${context}.queryValidator.`);
-  }
-  if (Object.prototype.hasOwnProperty.call(definition, "params")) {
-    throw new RouteDefinitionError(`${context}.params is not supported. Use ${context}.paramsValidator.`);
-  }
-  if (Object.prototype.hasOwnProperty.call(definition, "response")) {
-    throw new RouteDefinitionError(`${context}.response is not supported. Use ${context}.responseValidators.`);
+  const unsupportedKeys = Object.keys(definition).filter((key) => !VALIDATOR_OPTION_KEYS.includes(key));
+  if (unsupportedKeys.length > 0) {
+    throw new RouteDefinitionError(`${context}.${unsupportedKeys[0]} is not supported.`);
   }
 
   const meta = normalizeRouteValidatorMeta(definition.meta, {
     context
   });
-  const bodyValidator = normalizeRouteValidator(definition.bodyValidator, {
-    context: `${context}.bodyValidator`
+  const body = normalizeRouteSchemaSection(definition.body, {
+    context: `${context}.body`,
+    defaultMode: "patch"
   });
-  const queryValidator = normalizeRouteValidator(definition.queryValidator, {
-    context: `${context}.queryValidator`,
-    allowArray: true
+  const query = normalizeRouteSchemaSection(definition.query, {
+    context: `${context}.query`
   });
-  const paramsValidator = normalizeRouteValidator(definition.paramsValidator, {
-    context: `${context}.paramsValidator`,
-    allowArray: true
+  const params = normalizeRouteSchemaSection(definition.params, {
+    context: `${context}.params`
   });
 
   const advancedSource =
@@ -282,16 +189,23 @@ function normalizeRouteValidatorDefinition(sourceDefinition, { context = "route
     throw new RouteDefinitionError(`${context}.advanced must be an object.`);
   }
 
+  const unsupportedAdvancedKeys = Object.keys(advancedSource).filter(
+    (key) => !ADVANCED_VALIDATOR_OPTION_KEYS.includes(key)
+  );
+  if (unsupportedAdvancedKeys.length > 0) {
+    throw new RouteDefinitionError(`${context}.advanced.${unsupportedAdvancedKeys[0]} is not supported.`);
+  }
+
   const normalized = {
     meta,
-    bodyValidator,
-    queryValidator,
-    paramsValidator
+    body,
+    query,
+    params
   };
 
-  if (Object.prototype.hasOwnProperty.call(definition, "responseValidators")) {
-    normalized.responseValidators = normalizeResponseValidatorDefinition(definition.responseValidators, {
-      context: `${context}.responseValidators`
+  if (Object.prototype.hasOwnProperty.call(definition, "responses")) {
+    normalized.responses = normalizeResponseDefinition(definition.responses, {
+      context: `${context}.responses`
     });
   }
 
@@ -302,13 +216,6 @@ function normalizeRouteValidatorDefinition(sourceDefinition, { context = "route
     normalized.fastifySchema = fastifySchema;
   }
 
-  const jskitInput = normalizeAdvancedJskitInput(advancedSource, {
-    context
-  });
-  if (jskitInput) {
-    normalized.jskitInput = jskitInput;
-  }
-
   return Object.freeze(normalized);
 }
 
@@ -316,6 +223,14 @@ function compileNormalizedRouteValidator(normalizedValidator) {
   const schema = {};
   const input = {};
 
+  function createJsonRestSchemaInputTransform(definition, { defaultMode = "patch", context = "route validator" } = {}) {
+    return (payload) => validateSchemaPayload(definition, payload, {
+      phase: defaultMode === "replace" ? "output" : "input",
+      context,
+      statusCode: 400
+    });
+  }
+
   if (Array.isArray(normalizedValidator.meta?.tags) && normalizedValidator.meta.tags.length > 0) {
     schema.tags = [...normalizedValidator.meta.tags];
   }
@@ -323,32 +238,50 @@ function compileNormalizedRouteValidator(normalizedValidator) {
     schema.summary = normalizedValidator.meta.summary;
   }
 
-  if (Object.prototype.hasOwnProperty.call(normalizedValidator.bodyValidator, "schema")) {
-    schema.body = normalizedValidator.bodyValidator.schema;
-    input.body = typeof normalizedValidator.bodyValidator.normalize === "function"
-      ? normalizedValidator.bodyValidator.normalize
-      : passThroughInputSection;
+  if (normalizedValidator.body) {
+    schema.body = resolveSchemaTransportSchemaDefinition(normalizedValidator.body, {
+      defaultMode: "patch",
+      context: "route validator.body"
+    });
+    input.body = createJsonRestSchemaInputTransform(normalizedValidator.body, {
+      defaultMode: "patch",
+      context: "route validator.body"
+    });
   }
 
-  if (Object.prototype.hasOwnProperty.call(normalizedValidator.queryValidator, "schema")) {
-    schema.querystring = normalizedValidator.queryValidator.schema;
-    input.query = typeof normalizedValidator.queryValidator.normalize === "function"
-      ? normalizedValidator.queryValidator.normalize
-      : passThroughInputSection;
+  if (normalizedValidator.query) {
+    schema.querystring = resolveSchemaTransportSchemaDefinition(normalizedValidator.query, {
+      defaultMode: "patch",
+      context: "route validator.query"
+    });
+    input.query = createJsonRestSchemaInputTransform(normalizedValidator.query, {
+      defaultMode: "patch",
+      context: "route validator.query"
+    });
   }
 
-  if (Object.prototype.hasOwnProperty.call(normalizedValidator.paramsValidator, "schema")) {
-    schema.params = normalizedValidator.paramsValidator.schema;
-    input.params = typeof normalizedValidator.paramsValidator.normalize === "function"
-      ? normalizedValidator.paramsValidator.normalize
-      : passThroughInputSection;
+  if (normalizedValidator.params) {
+    schema.params = resolveSchemaTransportSchemaDefinition(normalizedValidator.params, {
+      defaultMode: "patch",
+      context: "route validator.params"
+    });
+    input.params = createJsonRestSchemaInputTransform(normalizedValidator.params, {
+      defaultMode: "patch",
+      context: "route validator.params"
+    });
   }
 
-  if (Object.prototype.hasOwnProperty.call(normalizedValidator, "responseValidators")) {
+  if (Object.prototype.hasOwnProperty.call(normalizedValidator, "responses")) {
     const responseSchema = {};
 
-    for (const [statusCode, entry] of Object.entries(normalizedValidator.responseValidators || {})) {
-      responseSchema[statusCode] = entry.schema;
+    for (const [statusCode, entry] of Object.entries(normalizedValidator.responses || {})) {
+      responseSchema[statusCode] =
+        entry && typeof entry === "object" && !Array.isArray(entry) && Object.prototype.hasOwnProperty.call(entry, "transportSchema")
+          ? entry.transportSchema
+          : resolveSchemaTransportSchemaDefinition(entry, {
+              defaultMode: "replace",
+              context: `route validator.responses.${statusCode}`
+            });
     }
 
     schema.response = responseSchema;
@@ -358,14 +291,10 @@ function compileNormalizedRouteValidator(normalizedValidator) {
     Object.assign(schema, normalizedValidator.fastifySchema);
   }
 
-  if (normalizedValidator.jskitInput) {
-    Object.assign(input, normalizedValidator.jskitInput);
-  }
-
   const compiled = {};
   if (Object.keys(schema).length > 0) {
     compiled.schema = Object.freeze({
-      ...schema
+      ...stripJsonRestTransportExtensions(schema)
     });
   }
   if (Object.keys(input).length > 0) {
@@ -433,14 +362,20 @@ function resolveRouteValidatorOptions({
     path
   });
 
+  const unsupportedRouteKeys = UNSUPPORTED_ROUTE_VALIDATOR_KEYS.filter((key) =>
+    Object.prototype.hasOwnProperty.call(normalizedOptions, key)
+  );
+  if (unsupportedRouteKeys.length > 0) {
+    throw new RouteDefinitionError(
+      `Route ${routeLabel} uses unsupported validator options: ${unsupportedRouteKeys.join(", ")}.`
+    );
+  }
+
   const hasInlineValidatorShape = VALIDATOR_OPTION_KEYS.some((key) => Object.prototype.hasOwnProperty.call(normalizedOptions, key));
 
   const remainingOptions = {
     ...normalizedOptions
   };
-  delete remainingOptions.schema;
-  delete remainingOptions.input;
-  delete remainingOptions.validator;
 
   if (!hasInlineValidatorShape) {
     return remainingOptions;