@jskit-ai/http-runtime 0.1.54 → 0.1.55

package/src/shared/validators/errorResponses.js

@@ -1,62 +1,114 @@
-import { Type } from "@fastify/type-provider-typebox";
+import { createSchema } from "json-rest-schema";
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
+import { createEmbeddableTransportSchemaDocument } from "./transportSchemaEmbedding.js";
 
-const fieldErrorsSchema = Type.Record(Type.String(), Type.String());
+const fieldErrorsFieldDefinition = deepFreeze({
+  type: "object",
+  values: {
+    type: "string",
+    minLength: 1
+  }
+});
 
-const apiErrorDetailsSchema = Type.Object(
-  {
-    fieldErrors: Type.Optional(fieldErrorsSchema)
-  },
-  {
-    additionalProperties: true
+const apiErrorDetailsSchema = createSchema({
+  fieldErrors: {
+    ...fieldErrorsFieldDefinition,
+    required: false
   }
-);
+});
 
-const apiErrorResponseSchema = Type.Object(
-  {
-    error: Type.String({ minLength: 1 }),
-    code: Type.Optional(Type.String({ minLength: 1 })),
-    details: Type.Optional(apiErrorDetailsSchema),
-    fieldErrors: Type.Optional(fieldErrorsSchema)
-  },
-  {
-    additionalProperties: false
+const apiValidationErrorDetailsSchema = createSchema({
+  fieldErrors: {
+    ...fieldErrorsFieldDefinition,
+    required: true
   }
-);
+});
 
-const apiValidationErrorResponseSchema = Type.Object(
-  {
-    error: Type.String({ minLength: 1 }),
-    code: Type.Optional(Type.String({ minLength: 1 })),
-    fieldErrors: fieldErrorsSchema,
-    details: Type.Object(
-      {
-        fieldErrors: fieldErrorsSchema
-      },
-      {
-        additionalProperties: true
+const apiErrorOutputValidator = deepFreeze({
+  schema: createSchema({
+    error: { type: "string", required: true, minLength: 1 },
+    code: { type: "string", required: false, minLength: 1 },
+    details: {
+      type: "object",
+      required: false,
+      schema: apiErrorDetailsSchema,
+      additionalProperties: true
+    },
+    fieldErrors: {
+      ...fieldErrorsFieldDefinition,
+      required: false
+    }
+  }),
+  mode: "replace"
+});
+
+const apiValidationErrorOutputValidator = deepFreeze({
+  schema: createSchema({
+    error: { type: "string", required: true, minLength: 1 },
+    code: { type: "string", required: false, minLength: 1 },
+    fieldErrors: {
+      ...fieldErrorsFieldDefinition,
+      required: true
+    },
+    details: {
+      type: "object",
+      required: true,
+      schema: apiValidationErrorDetailsSchema,
+      additionalProperties: true
+    }
+  }),
+  mode: "replace"
+});
+
+const apiErrorTransportSchema = apiErrorOutputValidator.schema.toJsonSchema({
+  mode: apiErrorOutputValidator.mode
+});
+
+const apiValidationErrorTransportSchema = apiValidationErrorOutputValidator.schema.toJsonSchema({
+  mode: apiValidationErrorOutputValidator.mode
+});
+
+const fastifyDefaultErrorTransportSchema = {
+  type: "object",
+  additionalProperties: true,
+  required: ["statusCode", "error", "message"],
+  properties: {
+    statusCode: { type: "integer", minimum: 400, maximum: 599 },
+    error: { type: "string", minLength: 1 },
+    message: { type: "string", minLength: 1 },
+    code: { type: "string", minLength: 1 },
+    details: {},
+    fieldErrors: {
+      type: "object",
+      additionalProperties: {
+        type: "string"
       }
-    )
-  },
-  {
-    additionalProperties: false
+    }
   }
+};
+
+const STANDARD_ERROR_STATUS_CODES = [400, 401, 403, 404, 409, 422, 429, 500, 503];
+
+function createTransportResponseSchema(schema = {}) {
+  return {
+    transportSchema: schema
+  };
+}
+
+const embeddedApiErrorTransportSchema = createEmbeddableTransportSchemaDocument(
+  apiErrorTransportSchema,
+  "ApiErrorOutput"
 );
 
-const fastifyDefaultErrorResponseSchema = Type.Object(
-  {
-    statusCode: Type.Integer({ minimum: 400, maximum: 599 }),
-    error: Type.String({ minLength: 1 }),
-    message: Type.String({ minLength: 1 }),
-    code: Type.Optional(Type.String({ minLength: 1 })),
-    details: Type.Optional(Type.Unknown()),
-    fieldErrors: Type.Optional(fieldErrorsSchema)
-  },
-  {
-    additionalProperties: true
-  }
+const embeddedApiValidationErrorTransportSchema = createEmbeddableTransportSchemaDocument(
+  apiValidationErrorTransportSchema,
+  "ApiValidationErrorOutput"
 );
 
-const STANDARD_ERROR_STATUS_CODES = [400, 401, 403, 404, 409, 422, 429, 500, 503];
+const sharedErrorTransportDefinitions = {
+  ...embeddedApiValidationErrorTransportSchema.definitions,
+  ...embeddedApiErrorTransportSchema.definitions
+};
 
 function passthroughErrorResponses(successResponses) {
   return successResponses;
@@ -73,35 +125,46 @@ function withStandardErrorResponses(successResponses, { includeValidation400 = f
     }
 
     if (statusCode === 400 && includeValidation400) {
-      responses[statusCode] = {
-        schema: Type.Union([
-          apiValidationErrorResponseSchema,
-          apiErrorResponseSchema,
-          fastifyDefaultErrorResponseSchema
-        ])
-      };
+      responses[statusCode] = createTransportResponseSchema({
+        anyOf: [
+          embeddedApiValidationErrorTransportSchema.schema,
+          embeddedApiErrorTransportSchema.schema,
+          fastifyDefaultErrorTransportSchema
+        ],
+        definitions: sharedErrorTransportDefinitions
+      });
       continue;
     }
 
-    responses[statusCode] = {
-      schema: Type.Union([apiErrorResponseSchema, fastifyDefaultErrorResponseSchema])
-    };
+    responses[statusCode] = createTransportResponseSchema({
+      anyOf: [
+        embeddedApiErrorTransportSchema.schema,
+        fastifyDefaultErrorTransportSchema
+      ],
+      definitions: embeddedApiErrorTransportSchema.definitions
+    });
   }
 
   return responses;
 }
 
 function enumSchema(values) {
-  return Type.Union(values.map((value) => Type.Literal(value)));
+  return {
+    anyOf: values.map((value) => ({ const: value }))
+  };
 }
 
 export {
-  fieldErrorsSchema,
+  fieldErrorsFieldDefinition,
   apiErrorDetailsSchema,
-  apiErrorResponseSchema,
-  apiValidationErrorResponseSchema,
-  fastifyDefaultErrorResponseSchema,
+  apiValidationErrorDetailsSchema,
+  apiErrorOutputValidator,
+  apiValidationErrorOutputValidator,
+  apiErrorTransportSchema,
+  apiValidationErrorTransportSchema,
+  fastifyDefaultErrorTransportSchema,
   STANDARD_ERROR_STATUS_CODES,
+  createTransportResponseSchema,
   passthroughErrorResponses,
   withStandardErrorResponses,
   enumSchema

package/src/shared/validators/httpValidatorsApi.js

@@ -1,12 +1,15 @@
 import { createPaginationQuerySchema } from "./paginationQuery.js";
-import { registerTypeBoxFormats, __testables } from "./typeboxFormats.js";
 import {
-  fieldErrorsSchema,
+  fieldErrorsFieldDefinition,
   apiErrorDetailsSchema,
-  apiErrorResponseSchema,
-  apiValidationErrorResponseSchema,
-  fastifyDefaultErrorResponseSchema,
+  apiValidationErrorDetailsSchema,
+  apiErrorOutputValidator,
+  apiValidationErrorOutputValidator,
+  apiErrorTransportSchema,
+  apiValidationErrorTransportSchema,
+  fastifyDefaultErrorTransportSchema,
   STANDARD_ERROR_STATUS_CODES,
+  createTransportResponseSchema,
   passthroughErrorResponses,
   withStandardErrorResponses,
   enumSchema
@@ -28,17 +31,55 @@ import {
   validateOperationSection,
   validateOperationInput
 } from "./operationValidation.js";
+import {
+  JSON_API_CONTENT_TYPE,
+  createJsonApiDocument,
+  createJsonApiErrorDocumentFromFailure,
+  createJsonApiErrorObject,
+  createJsonApiResourceObject,
+  isJsonApiCollectionDocument,
+  isJsonApiContentType,
+  isJsonApiErrorDocument,
+  isJsonApiResourceDocument,
+  isJsonContentType,
+  normalizeJsonApiDocument,
+  normalizeJsonApiResourceObject,
+  resolveJsonApiTransportTypes,
+  simplifyJsonApiDocument
+} from "./jsonApiTransport.js";
+import {
+  JSON_API_QUERY_PAGE_CURSOR_KEY,
+  JSON_API_QUERY_PAGE_LIMIT_KEY,
+  JSON_API_QUERY_INCLUDE_KEY,
+  JSON_API_QUERY_SORT_KEY,
+  mapPlainQueryKeyToTransportKey,
+  mapTransportQueryKeyToPlainKey,
+  encodeJsonApiResourceQueryObject,
+  decodeJsonApiResourceQueryObject,
+  createJsonApiResourceQueryTransportSchema
+} from "./jsonApiQueryTransport.js";
+import {
+  JSON_API_ERROR_DOCUMENT_SCHEMA,
+  createJsonApiResourceObjectTransportSchema,
+  createJsonApiResourceRequestBodyTransportSchema,
+  createJsonApiResourceSuccessTransportSchema,
+  withJsonApiErrorResponses,
+  createJsonApiResourceRouteTransport,
+  createJsonApiResourceRouteContract
+} from "./jsonApiRouteTransport.js";
 
 const HTTP_VALIDATORS_API = Object.freeze({
   createPaginationQuerySchema,
-  registerTypeBoxFormats,
-  __testables,
-  fieldErrorsSchema,
+  fieldErrorsFieldDefinition,
   apiErrorDetailsSchema,
-  apiErrorResponseSchema,
-  apiValidationErrorResponseSchema,
-  fastifyDefaultErrorResponseSchema,
+  apiValidationErrorDetailsSchema,
+  apiErrorOutputValidator,
+  apiValidationErrorOutputValidator,
+  apiErrorTransportSchema,
+  apiValidationErrorTransportSchema,
+  fastifyDefaultErrorTransportSchema,
   STANDARD_ERROR_STATUS_CODES,
+  createTransportResponseSchema,
   passthroughErrorResponses,
   withStandardErrorResponses,
   enumSchema,
@@ -52,7 +93,37 @@ const HTTP_VALIDATORS_API = Object.freeze({
   resolveIssueMessageFromSchema,
   mapOperationIssues,
   validateOperationSection,
-  validateOperationInput
+  validateOperationInput,
+  JSON_API_CONTENT_TYPE,
+  createJsonApiDocument,
+  createJsonApiErrorDocumentFromFailure,
+  createJsonApiErrorObject,
+  createJsonApiResourceObject,
+  isJsonApiCollectionDocument,
+  isJsonApiContentType,
+  isJsonApiErrorDocument,
+  isJsonApiResourceDocument,
+  isJsonContentType,
+  normalizeJsonApiDocument,
+  normalizeJsonApiResourceObject,
+  resolveJsonApiTransportTypes,
+  simplifyJsonApiDocument,
+  JSON_API_QUERY_PAGE_CURSOR_KEY,
+  JSON_API_QUERY_PAGE_LIMIT_KEY,
+  JSON_API_QUERY_INCLUDE_KEY,
+  JSON_API_QUERY_SORT_KEY,
+  mapPlainQueryKeyToTransportKey,
+  mapTransportQueryKeyToPlainKey,
+  encodeJsonApiResourceQueryObject,
+  decodeJsonApiResourceQueryObject,
+  createJsonApiResourceQueryTransportSchema,
+  JSON_API_ERROR_DOCUMENT_SCHEMA,
+  createJsonApiResourceObjectTransportSchema,
+  createJsonApiResourceRequestBodyTransportSchema,
+  createJsonApiResourceSuccessTransportSchema,
+  withJsonApiErrorResponses,
+  createJsonApiResourceRouteTransport,
+  createJsonApiResourceRouteContract
 });
 
 export { HTTP_VALIDATORS_API };

package/src/shared/validators/jsonApiQueryTransport.js

@@ -0,0 +1,211 @@
+import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveSchemaTransportSchemaDefinition } from "@jskit-ai/kernel/shared/validators";
+
+const JSON_API_QUERY_PAGE_CURSOR_KEY = "page[cursor]";
+const JSON_API_QUERY_PAGE_LIMIT_KEY = "page[limit]";
+const JSON_API_QUERY_INCLUDE_KEY = "include";
+const JSON_API_QUERY_SORT_KEY = "sort";
+const JSON_API_FILTER_PREFIX = "filter[";
+const JSON_API_FIELDS_PREFIX = "fields[";
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeQueryKey(key = "") {
+  return String(key || "").trim();
+}
+
+function buildFieldsTransportKey(responseType = "") {
+  const normalizedResponseType = normalizeText(responseType);
+  return normalizedResponseType ? `${JSON_API_FIELDS_PREFIX}${normalizedResponseType}]` : "";
+}
+
+function mapPlainQueryKeyToTransportKey(key = "", { responseType = "" } = {}) {
+  const normalizedKey = normalizeQueryKey(key);
+  if (!normalizedKey) {
+    return "";
+  }
+
+  if (normalizedKey === "cursor") {
+    return JSON_API_QUERY_PAGE_CURSOR_KEY;
+  }
+  if (normalizedKey === "limit") {
+    return JSON_API_QUERY_PAGE_LIMIT_KEY;
+  }
+  if (normalizedKey === "q") {
+    return `${JSON_API_FILTER_PREFIX}q]`;
+  }
+  if (normalizedKey === "include") {
+    return JSON_API_QUERY_INCLUDE_KEY;
+  }
+  if (normalizedKey === "sort") {
+    return JSON_API_QUERY_SORT_KEY;
+  }
+  if (normalizedKey === "fields") {
+    return buildFieldsTransportKey(responseType);
+  }
+
+  return `${JSON_API_FILTER_PREFIX}${normalizedKey}]`;
+}
+
+function mapTransportQueryKeyToPlainKey(key = "", { responseType = "" } = {}) {
+  const normalizedKey = normalizeQueryKey(key);
+  if (!normalizedKey) {
+    return "";
+  }
+
+  if (normalizedKey === JSON_API_QUERY_PAGE_CURSOR_KEY) {
+    return "cursor";
+  }
+  if (normalizedKey === JSON_API_QUERY_PAGE_LIMIT_KEY) {
+    return "limit";
+  }
+  if (normalizedKey === JSON_API_QUERY_INCLUDE_KEY) {
+    return "include";
+  }
+  if (normalizedKey === JSON_API_QUERY_SORT_KEY) {
+    return "sort";
+  }
+  if (normalizedKey === `${JSON_API_FILTER_PREFIX}q]`) {
+    return "q";
+  }
+
+  const fieldsTransportKey = buildFieldsTransportKey(responseType);
+  if (fieldsTransportKey && normalizedKey === fieldsTransportKey) {
+    return "fields";
+  }
+
+  if (normalizedKey.startsWith(JSON_API_FILTER_PREFIX) && normalizedKey.endsWith("]")) {
+    return normalizedKey.slice(JSON_API_FILTER_PREFIX.length, -1);
+  }
+
+  if (normalizedKey.startsWith(JSON_API_FIELDS_PREFIX) && normalizedKey.endsWith("]")) {
+    return "fields";
+  }
+
+  return normalizedKey;
+}
+
+function normalizeTransportQueryScalar(value) {
+  if (Array.isArray(value)) {
+    const normalizedValues = value
+      .map((entry) => String(entry ?? "").trim())
+      .filter(Boolean);
+    if (normalizedValues.length < 1) {
+      return "";
+    }
+    return normalizedValues.join(",");
+  }
+
+  return String(value ?? "").trim();
+}
+
+function encodeJsonApiResourceQueryObject(query = {}, { responseType = "" } = {}) {
+  if (!isRecord(query)) {
+    return Object.freeze({});
+  }
+
+  const source = normalizeObject(query);
+  const encoded = {};
+
+  for (const [rawKey, rawValue] of Object.entries(source)) {
+    const transportKey = mapPlainQueryKeyToTransportKey(rawKey, {
+      responseType
+    });
+    if (!transportKey) {
+      continue;
+    }
+
+    const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+    const normalizedValues = values
+      .map((entry) => String(entry ?? "").trim())
+      .filter(Boolean);
+    if (normalizedValues.length < 1) {
+      continue;
+    }
+
+    encoded[transportKey] = normalizedValues.length === 1 ? normalizedValues[0] : normalizedValues;
+  }
+
+  return Object.freeze(encoded);
+}
+
+function decodeJsonApiResourceQueryObject(query = {}, { responseType = "" } = {}) {
+  if (!isRecord(query)) {
+    return Object.freeze({});
+  }
+
+  const source = normalizeObject(query);
+  const decoded = {};
+
+  for (const [rawKey, rawValue] of Object.entries(source)) {
+    const plainKey = mapTransportQueryKeyToPlainKey(rawKey, {
+      responseType
+    });
+    if (!plainKey) {
+      continue;
+    }
+
+    const normalizedValue = normalizeTransportQueryScalar(rawValue);
+    if (!normalizedValue) {
+      continue;
+    }
+
+    decoded[plainKey] = normalizedValue;
+  }
+
+  return Object.freeze(decoded);
+}
+
+function createJsonApiResourceQueryTransportSchema({
+  query,
+  responseType = ""
+} = {}) {
+  const transportSchema = resolveSchemaTransportSchemaDefinition(query, {
+    context: "JSON:API resource query",
+    defaultMode: "patch"
+  });
+
+  if (!transportSchema || typeof transportSchema !== "object" || Array.isArray(transportSchema)) {
+    throw new TypeError("JSON:API resource query transport schema must resolve to an object schema.");
+  }
+
+  const sourceSchema = normalizeObject(transportSchema);
+  const sourceProperties = normalizeObject(sourceSchema.properties);
+  const properties = {};
+
+  for (const [plainKey, propertySchema] of Object.entries(sourceProperties)) {
+    const transportKey = mapPlainQueryKeyToTransportKey(plainKey, {
+      responseType
+    });
+    if (!transportKey) {
+      continue;
+    }
+    properties[transportKey] = propertySchema;
+  }
+
+  const schema = {
+    type: "object",
+    additionalProperties: false,
+    properties
+  };
+
+  if (isRecord(sourceSchema.definitions) && Object.keys(sourceSchema.definitions).length > 0) {
+    schema.definitions = normalizeObject(sourceSchema.definitions);
+  }
+
+  return schema;
+}
+
+export {
+  JSON_API_QUERY_PAGE_CURSOR_KEY,
+  JSON_API_QUERY_PAGE_LIMIT_KEY,
+  JSON_API_QUERY_INCLUDE_KEY,
+  JSON_API_QUERY_SORT_KEY,
+  mapPlainQueryKeyToTransportKey,
+  mapTransportQueryKeyToPlainKey,
+  encodeJsonApiResourceQueryObject,
+  decodeJsonApiResourceQueryObject,
+  createJsonApiResourceQueryTransportSchema
+};

package/src/shared/validators/jsonApiResponses.js

@@ -0,0 +1,3 @@
+export {
+  simplifyJsonApiDocument
+} from "./jsonApiTransport.js";

package/src/shared/validators/jsonApiResult.js

@@ -0,0 +1,83 @@
+const JSON_API_RESULT_MARKER = "__jskitJsonApiResult";
+const JSON_API_RESULT_KINDS = Object.freeze([
+  "data",
+  "document",
+  "meta"
+]);
+
+function normalizeJsonApiResultKind(kind = "") {
+  const normalizedKind = String(kind || "").trim().toLowerCase();
+  if (!JSON_API_RESULT_KINDS.includes(normalizedKind)) {
+    throw new TypeError(`Unsupported JSON:API result kind: ${normalizedKind || "<empty>"}.`);
+  }
+
+  return normalizedKind;
+}
+
+function createJsonApiResult(kind, value) {
+  return Object.freeze({
+    [JSON_API_RESULT_MARKER]: true,
+    kind: normalizeJsonApiResultKind(kind),
+    value
+  });
+}
+
+function isJsonApiResult(value) {
+  return Boolean(value) &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    value[JSON_API_RESULT_MARKER] === true &&
+    JSON_API_RESULT_KINDS.includes(String(value.kind || "").trim().toLowerCase());
+}
+
+function isJsonApiResultKind(value, kind) {
+  return isJsonApiResult(value) && value.kind === normalizeJsonApiResultKind(kind);
+}
+
+function returnJsonApiData(data) {
+  return createJsonApiResult("data", data);
+}
+
+function returnJsonApiDocument(document) {
+  return createJsonApiResult("document", document);
+}
+
+function returnJsonApiMeta(meta) {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
+    throw new TypeError("returnJsonApiMeta requires a meta object.");
+  }
+
+  return createJsonApiResult("meta", meta);
+}
+
+function isJsonApiDataResult(value) {
+  return isJsonApiResultKind(value, "data");
+}
+
+function isJsonApiDocumentResult(value) {
+  return isJsonApiResultKind(value, "document");
+}
+
+function isJsonApiMetaResult(value) {
+  return isJsonApiResultKind(value, "meta");
+}
+
+function unwrapJsonApiResult(value) {
+  if (!isJsonApiResult(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+export {
+  JSON_API_RESULT_MARKER,
+  returnJsonApiData,
+  returnJsonApiDocument,
+  returnJsonApiMeta,
+  isJsonApiResult,
+  isJsonApiDataResult,
+  isJsonApiDocumentResult,
+  isJsonApiMetaResult,
+  unwrapJsonApiResult
+};