@jskit-ai/http-runtime 0.1.54 → 0.1.56

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   "packageVersion": 1,
   "packageId": "@jskit-ai/http-runtime",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "kind": "runtime",
   "dependsOn": [],
   "capabilities": {
@@ -67,9 +67,7 @@ export default Object.freeze({
   "mutations": {
     "dependencies": {
       "runtime": {
-        "@jskit-ai/kernel": "0.1.55",
-        "@fastify/type-provider-typebox": "^6.1.0",
-        "typebox": "^1.0.81"
+        "@jskit-ai/kernel": "0.1.57"
       },
       "dev": {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/http-runtime",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -9,16 +9,16 @@
     "./client": "./src/client/index.js",
     "./shared": "./src/shared/index.js",
     "./shared/validators/errorResponses": "./src/shared/validators/errorResponses.js",
+    "./shared/validators/jsonApiResult": "./src/shared/validators/jsonApiResult.js",
+    "./shared/validators/jsonApiRouteTransport": "./src/shared/validators/jsonApiRouteTransport.js",
     "./shared/validators/paginationQuery": "./src/shared/validators/paginationQuery.js",
     "./shared/validators/command": "./src/shared/validators/command.js",
     "./shared/validators/resource": "./src/shared/validators/resource.js",
-    "./shared/validators/typeboxFormats": "./src/shared/validators/typeboxFormats.js",
     "./shared/validators/operationMessages": "./src/shared/validators/operationMessages.js",
     "./shared/validators/operationValidation": "./src/shared/validators/operationValidation.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.55",
-    "@fastify/type-provider-typebox": "^6.1.0",
-    "typebox": "^1.0.81"
+    "@jskit-ai/kernel": "0.1.57",
+    "json-rest-schema": "1.x.x"
   }
 }

package/src/shared/clientRuntime/client.js

@@ -1,6 +1,15 @@
 import { createHttpError, createNetworkError } from "./errors.js";
 import { hasHeader, setHeaderIfMissing } from "./headers.js";
 import { DEFAULT_RETRYABLE_CSRF_ERROR_CODES, shouldRetryForCsrfFailure } from "./retry.js";
+import { appendQueryString } from "@jskit-ai/kernel/shared/support";
+import { isJsonContentType } from "../validators/jsonApiTransport.js";
+import {
+  JSON_API_CONTENT_TYPE,
+  decodeJsonApiResourceResponse,
+  encodeJsonApiResourceRequestBody,
+  encodeJsonApiResourceQuery,
+  normalizeJsonApiClientTransport
+} from "./jsonApiResourceTransport.js";
 
 const DEFAULT_UNSAFE_METHODS = Object.freeze(["POST", "PUT", "PATCH", "DELETE"]);
 const DEFAULT_NDJSON_CONTENT_TYPE = "application/x-ndjson";
@@ -28,9 +37,58 @@ function isObjectBody(value) {
   return Boolean(value) && typeof value === "object" && !(value instanceof FormData);
 }
 
+function isQueryValuePresent(value) {
+  if (Array.isArray(value)) {
+    return value.some((entry) => String(entry ?? "").trim());
+  }
+  return String(value ?? "").trim().length > 0;
+}
+
+function appendRequestQueryToUrl(url, query = null, transport = null) {
+  const normalizedUrl = String(url || "").trim();
+  if (!normalizedUrl) {
+    return "";
+  }
+
+  const encodedQuery =
+    transport
+      ? encodeJsonApiResourceQuery(query, transport)
+      : query && typeof query === "object" && !Array.isArray(query)
+        ? query
+        : null;
+
+  if (!encodedQuery || typeof encodedQuery !== "object" || Array.isArray(encodedQuery)) {
+    return normalizedUrl;
+  }
+
+  const searchParams = new URLSearchParams();
+  for (const [key, rawValue] of Object.entries(encodedQuery)) {
+    const normalizedKey = String(key || "").trim();
+    if (!normalizedKey || !isQueryValuePresent(rawValue)) {
+      continue;
+    }
+
+    const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+    for (const value of values) {
+      const normalizedValue = String(value ?? "").trim();
+      if (!normalizedValue) {
+        continue;
+      }
+      searchParams.append(normalizedKey, normalizedValue);
+    }
+  }
+
+  const serializedQuery = searchParams.toString();
+  if (!serializedQuery) {
+    return normalizedUrl;
+  }
+
+  return appendQueryString(normalizedUrl, serializedQuery);
+}
+
 function parseJsonSafely(response) {
   const contentType = String(response?.headers?.get?.("content-type") || "");
-  const isJson = contentType.includes("application/json");
+  const isJson = isJsonContentType(contentType);
   if (!isJson) {
     return Promise.resolve({
       contentType,
@@ -256,11 +314,18 @@ function createHttpClient(options = {}) {
     const resolvedState = resolveRequestState(state);
 
     const method = normalizeMethod(requestOptions.method);
+    const transport = normalizeJsonApiClientTransport(requestOptions.transport);
+    const {
+      transport: _transport,
+      query: requestQuery,
+      ...forwardedRequestOptions
+    } = requestOptions && typeof requestOptions === "object" ? requestOptions : {};
+    const requestUrl = appendRequestQueryToUrl(url, requestQuery, transport);
     const headers =
       requestOptions.headers && typeof requestOptions.headers === "object" ? { ...requestOptions.headers } : {};
 
     const decorateHeadersResult = decorateHeaders({
-      url,
+      url: requestUrl,
       method,
       headers,
       requestOptions,
@@ -273,11 +338,20 @@ function createHttpClient(options = {}) {
 
     const config = {
       credentials: String(options?.credentials || "same-origin"),
-      ...requestOptions,
+      ...forwardedRequestOptions,
       method,
       headers
     };
 
+    if (transport) {
+      setHeaderIfMissing(headers, "Accept", JSON_API_CONTENT_TYPE);
+    }
+
+    if (transport && isObjectBody(config.body)) {
+      setHeaderIfMissing(headers, "Content-Type", JSON_API_CONTENT_TYPE);
+      config.body = encodeJsonApiResourceRequestBody(config.body, transport);
+    }
+
     if (isObjectBody(config.body)) {
       setHeaderIfMissing(headers, "Content-Type", "application/json");
       config.body = JSON.stringify(config.body);
@@ -293,7 +367,9 @@ function createHttpClient(options = {}) {
     return {
       method,
       config,
-      state: resolvedState
+      state: resolvedState,
+      transport,
+      url: requestUrl
     };
   }
 
@@ -383,7 +459,7 @@ function createHttpClient(options = {}) {
       state: resolvedState
     } = requestContext;
     const result = await executePreparedRequest(
-      url,
+      requestContext.url,
       requestContext.config,
       requestContext,
       (cause) =>
@@ -420,7 +496,8 @@ function createHttpClient(options = {}) {
       value: {
         method,
         state: resolvedState,
-        result
+        result,
+        transport: requestContext.transport
       }
     };
   }
@@ -454,20 +531,60 @@ function createHttpClient(options = {}) {
     const {
       method,
       state: resolvedState,
-      result
+      result,
+      transport
     } = execution.value;
 
+    if (Number(result.response?.status || 200) === 204) {
+      await notifySuccess({
+        url,
+        method,
+        state: resolvedState,
+        response: result.response,
+        data: null,
+        rawData: null,
+        contentType: result.contentType,
+        isJson: result.isJson,
+        stream: false
+      });
+      return null;
+    }
+
+    let responseData = result.data;
+    if (transport) {
+      try {
+        responseData = decodeJsonApiResourceResponse(result.data, transport);
+      } catch (cause) {
+        const error = createNetworkError(cause);
+        error.message = "JSON:API response decoding failed.";
+        await notifyFailure({
+          url,
+          method,
+          state: resolvedState,
+          reason: "transport_decode_error",
+          error,
+          response: result.response,
+          data: result.data,
+          contentType: result.contentType,
+          isJson: result.isJson,
+          stream: false
+        });
+        throw error;
+      }
+    }
+
     await notifySuccess({
       url,
       method,
       state: resolvedState,
       response: result.response,
-      data: result.data,
+      data: responseData,
+      rawData: result.data,
       contentType: result.contentType,
       isJson: result.isJson,
       stream: false
     });
-    return result.data;
+    return responseData;
   }
 
   async function requestStream(url, requestOptions = {}, handlers = {}, state = null) {

package/src/shared/clientRuntime/errors.js

@@ -1,7 +1,13 @@
 import { isRecord, resolveFieldErrors } from "../support/fieldErrors.js";
+import { createJsonApiClientErrorPayload } from "./jsonApiResourceTransport.js";
 
 function createHttpError(response, data = {}) {
   const payload = isRecord(data) ? data : {};
+  const jsonApiPayload = createJsonApiClientErrorPayload(payload);
+  if (jsonApiPayload) {
+    return createHttpError(response, jsonApiPayload);
+  }
+
   const error = new Error(payload.error || `Request failed with status ${response.status}.`);
   const normalizedFieldErrors = resolveFieldErrors(payload);
   error.status = Number(response?.status || 0);

package/src/shared/clientRuntime/jsonApiResourceTransport.js

@@ -0,0 +1,241 @@
+import { normalizeArray, normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  JSON_API_CONTENT_TYPE,
+  createJsonApiDocument,
+  createJsonApiResourceObject,
+  normalizeJsonApiDocument,
+  resolveJsonApiTransportTypes
+} from "../validators/jsonApiTransport.js";
+import { encodeJsonApiResourceQueryObject } from "../validators/jsonApiQueryTransport.js";
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeTransportKind(transport = null) {
+  return String(transport?.kind || "").trim().toLowerCase();
+}
+
+function isJsonApiResourceTransport(transport = null) {
+  return normalizeTransportKind(transport) === "jsonapi-resource";
+}
+
+function normalizeJsonApiClientTransport(transport = null) {
+  if (!isJsonApiResourceTransport(transport)) {
+    return null;
+  }
+
+  const resolvedTypes = resolveJsonApiTransportTypes(transport, {
+    context: "JSON:API client transport"
+  });
+
+  return Object.freeze({
+    kind: "jsonapi-resource",
+    requestType: resolvedTypes.requestType,
+    responseType: resolvedTypes.responseType,
+    responseKind: normalizeText(transport?.responseKind, {
+      fallback: "record"
+    }).toLowerCase(),
+    includeBodyId: transport?.includeBodyId === true
+  });
+}
+
+function defaultEncodeAttributes(body = {}) {
+  const source = normalizeObject(body);
+  const attributes = {
+    ...source
+  };
+  delete attributes.id;
+  return attributes;
+}
+
+function encodeJsonApiResourceRequestBody(body, transport = null) {
+  const normalizedTransport = normalizeJsonApiClientTransport(transport);
+  if (!normalizedTransport) {
+    return body;
+  }
+
+  if (!isRecord(body)) {
+    throw new TypeError("JSON:API resource request body must be an object.");
+  }
+
+  if (!normalizedTransport.requestType) {
+    throw new TypeError("JSON:API resource request body requires requestType.");
+  }
+
+  const source = normalizeObject(body);
+  return createJsonApiDocument({
+    data: createJsonApiResourceObject({
+      type: normalizedTransport.requestType,
+      ...(normalizedTransport.includeBodyId && source.id != null ? { id: source.id } : {}),
+      attributes: defaultEncodeAttributes(source)
+    })
+  });
+}
+
+function encodeJsonApiResourceQuery(query, transport = null) {
+  const normalizedTransport = normalizeJsonApiClientTransport(transport);
+  if (!normalizedTransport) {
+    return query;
+  }
+
+  return encodeJsonApiResourceQueryObject(query, {
+    responseType: normalizedTransport.responseType
+  });
+}
+
+function simplifyResourceObject(resource = {}) {
+  const normalizedResource = isRecord(resource) ? normalizeObject(resource) : {};
+  return {
+    id: normalizedResource.id == null ? "" : String(normalizedResource.id),
+    ...(normalizeObject(normalizedResource.attributes))
+  };
+}
+
+function assertPrimaryDataType(resource = {}, expectedType = "") {
+  const normalizedExpectedType = normalizeText(expectedType);
+  if (!normalizedExpectedType) {
+    return;
+  }
+
+  const actualType = normalizeText(resource?.type);
+  if (actualType && actualType !== normalizedExpectedType) {
+    throw new Error(`Expected JSON:API resource type ${normalizedExpectedType}, received ${actualType}.`);
+  }
+}
+
+function resolveCollectionPageMeta(document = {}) {
+  const nextCursor = normalizeText(
+    document?.meta?.page?.nextCursor || document?.meta?.pagination?.cursor?.next
+  );
+  return {
+    nextCursor: nextCursor || null,
+    ...(isRecord(document?.meta) ? { meta: document.meta } : {}),
+    ...(isRecord(document?.links) ? { links: document.links } : {})
+  };
+}
+
+function decodeJsonApiResourceResponse(payload, transport = null) {
+  const normalizedTransport = normalizeJsonApiClientTransport(transport);
+  if (!normalizedTransport) {
+    return payload;
+  }
+
+  const document = normalizeJsonApiDocument(payload);
+  if (document.kind === "unknown") {
+    throw new Error("Expected JSON:API response document.");
+  }
+
+  if (normalizedTransport.responseKind === "collection") {
+    if (document.kind !== "collection") {
+      throw new Error("Expected JSON:API collection document.");
+    }
+
+    for (const entry of document.data) {
+      assertPrimaryDataType(entry, normalizedTransport.responseType);
+    }
+
+    return {
+      items: document.data.map((entry) => simplifyResourceObject(entry)),
+      ...resolveCollectionPageMeta(document)
+    };
+  }
+
+  if (normalizedTransport.responseKind === "meta") {
+    if (document.kind !== "meta") {
+      throw new Error("Expected JSON:API meta document.");
+    }
+
+    return isRecord(document.meta) ? document.meta : {};
+  }
+
+  if (normalizedTransport.responseKind === "nullable-record") {
+    if (document.kind !== "resource") {
+      throw new Error("Expected JSON:API resource document.");
+    }
+
+    if (document.data != null) {
+      assertPrimaryDataType(document.data, normalizedTransport.responseType);
+    }
+
+    return document.data == null ? null : simplifyResourceObject(document.data);
+  }
+
+  if (document.kind !== "resource") {
+    throw new Error("Expected JSON:API resource document.");
+  }
+
+  if (document.data != null) {
+    assertPrimaryDataType(document.data, normalizedTransport.responseType);
+  }
+
+  return document.data == null ? null : simplifyResourceObject(document.data);
+}
+
+function decodeJsonApiErrorFieldErrors(payload = {}) {
+  const document = normalizeJsonApiDocument(payload);
+  if (document.kind !== "errors") {
+    return {};
+  }
+
+  const fieldErrors = {};
+  for (const error of normalizeArray(document.errors)) {
+    const pointer = normalizeText(error?.source?.pointer);
+    const parameter = normalizeText(error?.source?.parameter);
+    const detail = normalizeText(error?.detail || error?.title, {
+      fallback: "Invalid value."
+    });
+
+    if (parameter && !Object.hasOwn(fieldErrors, parameter)) {
+      fieldErrors[parameter] = detail;
+      continue;
+    }
+
+    if (!pointer.startsWith("/data/attributes/")) {
+      continue;
+    }
+
+    const fieldName = normalizeText(pointer.slice("/data/attributes/".length).split("/")[0]);
+    if (fieldName && !Object.hasOwn(fieldErrors, fieldName)) {
+      fieldErrors[fieldName] = detail;
+    }
+  }
+
+  return fieldErrors;
+}
+
+function createJsonApiClientErrorPayload(payload = {}) {
+  const document = normalizeJsonApiDocument(payload);
+  if (document.kind !== "errors") {
+    return null;
+  }
+
+  const firstError = normalizeArray(document.errors)[0] || {};
+  const fieldErrors = decodeJsonApiErrorFieldErrors(payload);
+
+  return {
+    error: normalizeText(firstError.detail || firstError.title, {
+      fallback: "Request failed."
+    }),
+    code: normalizeText(firstError.code) || null,
+    ...(Object.keys(fieldErrors).length > 0
+      ? {
+          fieldErrors,
+          details: {
+            fieldErrors
+          }
+        }
+      : {})
+  };
+}
+
+export {
+  JSON_API_CONTENT_TYPE,
+  isJsonApiResourceTransport,
+  normalizeJsonApiClientTransport,
+  encodeJsonApiResourceRequestBody,
+  encodeJsonApiResourceQuery,
+  decodeJsonApiResourceResponse,
+  decodeJsonApiErrorFieldErrors,
+  createJsonApiClientErrorPayload
+};

package/src/shared/index.js

@@ -1,12 +1,15 @@
 export { createPaginationQuerySchema } from "./validators/paginationQuery.js";
-export { registerTypeBoxFormats, __testables } from "./validators/typeboxFormats.js";
 export {
-  fieldErrorsSchema,
+  fieldErrorsFieldDefinition,
   apiErrorDetailsSchema,
-  apiErrorResponseSchema,
-  apiValidationErrorResponseSchema,
-  fastifyDefaultErrorResponseSchema,
+  apiValidationErrorDetailsSchema,
+  apiErrorOutputValidator,
+  apiValidationErrorOutputValidator,
+  apiErrorTransportSchema,
+  apiValidationErrorTransportSchema,
+  fastifyDefaultErrorTransportSchema,
   STANDARD_ERROR_STATUS_CODES,
+  createTransportResponseSchema,
   passthroughErrorResponses,
   withStandardErrorResponses,
   enumSchema
@@ -28,3 +31,49 @@ export {
   validateOperationSection,
   validateOperationInput
 } from "./validators/operationValidation.js";
+export {
+  JSON_API_CONTENT_TYPE,
+  createJsonApiDocument,
+  createJsonApiErrorDocumentFromFailure,
+  createJsonApiErrorObject,
+  createJsonApiResourceObject,
+  isJsonApiCollectionDocument,
+  isJsonApiContentType,
+  isJsonApiErrorDocument,
+  isJsonApiResourceDocument,
+  isJsonContentType,
+  normalizeJsonApiDocument,
+  normalizeJsonApiResourceObject,
+  resolveJsonApiTransportTypes,
+  simplifyJsonApiDocument
+} from "./validators/jsonApiTransport.js";
+export {
+  returnJsonApiData,
+  returnJsonApiDocument,
+  returnJsonApiMeta,
+  isJsonApiResult,
+  isJsonApiDataResult,
+  isJsonApiDocumentResult,
+  isJsonApiMetaResult,
+  unwrapJsonApiResult
+} from "./validators/jsonApiResult.js";
+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
+} from "./validators/jsonApiQueryTransport.js";
+export {
+  JSON_API_ERROR_DOCUMENT_SCHEMA,
+  createJsonApiResourceObjectTransportSchema,
+  createJsonApiResourceRequestBodyTransportSchema,
+  createJsonApiResourceSuccessTransportSchema,
+  withJsonApiErrorResponses,
+  createJsonApiResourceRouteTransport,
+  createJsonApiResourceRouteContract
+} from "./validators/jsonApiRouteTransport.js";

package/src/shared/validators/command.js

@@ -1,5 +1,6 @@
-import { asSchema } from "./schemaUtils.js";
+import { asSchemaDefinition } from "./schemaUtils.js";
 import { normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
+import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
 
 function createCommand({
   input,
@@ -8,8 +9,8 @@ function createCommand({
   invalidates = []
 } = {}) {
   const command = {
-    input: asSchema(input, "input"),
-    output: asSchema(output, "output"),
+    input: asSchemaDefinition(input, "input", "patch"),
+    output: asSchemaDefinition(output, "output", "replace"),
     invalidates: Object.freeze(normalizeUniqueTextList(invalidates))
   };
 
@@ -17,7 +18,7 @@ function createCommand({
     command.idempotent = idempotent;
   }
 
-  return Object.freeze(command);
+  return deepFreeze(command);
 }
 
 export { createCommand };