@jskit-ai/http-runtime 0.1.133 → 0.1.135

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   "packageVersion": 1,
   "packageId": "@jskit-ai/http-runtime",
-  "version": "0.1.133",
+  "version": "0.1.135",
   "kind": "runtime",
   "dependsOn": [],
   "capabilities": {
@@ -67,7 +67,7 @@ export default Object.freeze({
   "mutations": {
     "dependencies": {
       "runtime": {
-        "@jskit-ai/kernel": "0.1.135"
+        "@jskit-ai/kernel": "0.1.137"
       },
       "dev": {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/http-runtime",
-  "version": "0.1.133",
+  "version": "0.1.135",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -18,7 +18,7 @@
     "./shared/validators/operationValidation": "./src/shared/validators/operationValidation.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.135",
+    "@jskit-ai/kernel": "0.1.137",
     "json-rest-schema": "1.x.x"
   }
 }

package/src/shared/validators/jsonApiQueryTransport.js

@@ -1,4 +1,8 @@
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  normalizeJsonApiFieldList,
+  normalizeJsonApiFieldsets
+} from "@jskit-ai/kernel/shared/support/jsonApiFieldsets";
 import { resolveSchemaTransportSchemaDefinition } from "@jskit-ai/kernel/shared/validators";
 
 const JSON_API_QUERY_PAGE_CURSOR_KEY = "page[cursor]";
@@ -21,6 +25,50 @@ function buildFieldsTransportKey(responseType = "") {
   return normalizedResponseType ? `${JSON_API_FIELDS_PREFIX}${normalizedResponseType}]` : "";
 }
 
+function parseFieldsTransportType(key = "") {
+  const normalizedKey = normalizeQueryKey(key);
+  if (!normalizedKey.startsWith(JSON_API_FIELDS_PREFIX) || !normalizedKey.endsWith("]")) {
+    return "";
+  }
+
+  return normalizeText(normalizedKey.slice(JSON_API_FIELDS_PREFIX.length, -1));
+}
+
+function addJsonApiFieldset(fieldsets, type = "", value = []) {
+  const normalizedType = normalizeText(type);
+  const fields = normalizeJsonApiFieldList(value);
+  if (!normalizedType || fields.length < 1) {
+    return;
+  }
+
+  fieldsets.set(
+    normalizedType,
+    normalizeJsonApiFieldList([
+      ...(fieldsets.get(normalizedType) || []),
+      ...fields
+    ])
+  );
+}
+
+function createJsonApiFieldsTransportValueSchema() {
+  return {
+    anyOf: [
+      {
+        type: "string",
+        minLength: 1
+      },
+      {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "string",
+          minLength: 1
+        }
+      }
+    ]
+  };
+}
+
 function mapPlainQueryKeyToTransportKey(key = "", { responseType = "" } = {}) {
   const normalizedKey = normalizeQueryKey(key);
   if (!normalizedKey) {
@@ -110,6 +158,15 @@ function encodeJsonApiResourceQueryObject(query = {}, { responseType = "" } = {}
   const encoded = {};
 
   for (const [rawKey, rawValue] of Object.entries(source)) {
+    if (normalizeQueryKey(rawKey) === "fields") {
+      for (const [type, fields] of Object.entries(normalizeJsonApiFieldsets(rawValue, {
+        primaryType: responseType
+      }))) {
+        encoded[buildFieldsTransportKey(type)] = fields.join(",");
+      }
+      continue;
+    }
+
     const transportKey = mapPlainQueryKeyToTransportKey(rawKey, {
       responseType
     });
@@ -138,8 +195,20 @@ function decodeJsonApiResourceQueryObject(query = {}, { responseType = "" } = {}
 
   const source = normalizeObject(query);
   const decoded = {};
+  const fieldsets = new Map();
 
   for (const [rawKey, rawValue] of Object.entries(source)) {
+    if (normalizeQueryKey(rawKey) === "fields") {
+      addJsonApiFieldset(fieldsets, responseType, rawValue);
+      continue;
+    }
+
+    const fieldsetType = parseFieldsTransportType(rawKey);
+    if (fieldsetType) {
+      addJsonApiFieldset(fieldsets, fieldsetType, rawValue);
+      continue;
+    }
+
     const plainKey = mapTransportQueryKeyToPlainKey(rawKey, {
       responseType
     });
@@ -155,6 +224,11 @@ function decodeJsonApiResourceQueryObject(query = {}, { responseType = "" } = {}
     decoded[plainKey] = normalizedValue;
   }
 
+  const normalizedFieldsets = normalizeJsonApiFieldsets(Object.fromEntries(fieldsets));
+  if (Object.keys(normalizedFieldsets).length > 0) {
+    decoded.fields = normalizedFieldsets;
+  }
+
   return Object.freeze(decoded);
 }
 
@@ -174,8 +248,16 @@ function createJsonApiResourceQueryTransportSchema({
   const sourceSchema = normalizeObject(transportSchema);
   const sourceProperties = normalizeObject(sourceSchema.properties);
   const properties = {};
+  const patternProperties = {};
 
   for (const [plainKey, propertySchema] of Object.entries(sourceProperties)) {
+    if (plainKey === "fields") {
+      properties.fields = createJsonApiFieldsTransportValueSchema();
+      patternProperties["^fields\\[[^\\[\\]]+\\]$"] =
+        createJsonApiFieldsTransportValueSchema();
+      continue;
+    }
+
     const transportKey = mapPlainQueryKeyToTransportKey(plainKey, {
       responseType
     });
@@ -190,6 +272,9 @@ function createJsonApiResourceQueryTransportSchema({
     additionalProperties: false,
     properties
   };
+  if (Object.keys(patternProperties).length > 0) {
+    schema.patternProperties = patternProperties;
+  }
 
   if (isRecord(sourceSchema.definitions) && Object.keys(sourceSchema.definitions).length > 0) {
     schema.definitions = normalizeObject(sourceSchema.definitions);

package/src/shared/validators/jsonApiRouteTransport.js

@@ -169,7 +169,8 @@ function resolveEmbeddedAttributesTransportSchema(definition, {
   context = "JSON:API resource",
   defaultMode = "replace",
   removeId = false,
-  removeKeys = []
+  removeKeys = [],
+  allowSparseFields = false
 } = {}) {
   const transportSchema = resolveSchemaTransportSchemaDefinition(definition, {
     context,
@@ -204,7 +205,7 @@ function resolveEmbeddedAttributesTransportSchema(definition, {
     return isRecord(fieldDefinitions) ? fieldDefinitions : {};
   })();
 
-  const required = Array.isArray(sourceSchema.required)
+  const required = allowSparseFields !== true && Array.isArray(sourceSchema.required)
     ? sourceSchema.required.filter((entry) => {
         const normalizedEntry = String(entry || "").trim();
         if (!normalizedEntry || excludedKeys.has(normalizedEntry)) {
@@ -341,7 +342,8 @@ function createJsonApiResourceObjectTransportSchema({
   includeMeta = false,
   excludeAttributeKeys = [],
   relationshipEntries = [],
-  relationshipMembersRequired = false
+  relationshipMembersRequired = false,
+  allowSparseFields = false
 } = {}) {
   const normalizedType = resolveRouteType(type);
   const relationshipsTransport = createJsonApiRelationshipsTransportSchema(relationshipEntries, {
@@ -357,7 +359,8 @@ function createJsonApiResourceObjectTransportSchema({
     removeKeys: [
       ...normalizeArray(excludeAttributeKeys),
       ...relationFieldKeys,
-    ]
+    ],
+    allowSparseFields
   });
 
   const properties = {
@@ -366,7 +369,7 @@ function createJsonApiResourceObjectTransportSchema({
     },
     attributes: embeddedAttributes.schema
   };
-  const required = ["type", "attributes"];
+  const required = allowSparseFields === true ? ["type"] : ["type", "attributes"];
 
   if (requireId) {
     properties.id = JSON_API_ID_SCHEMA;
@@ -457,6 +460,7 @@ function createJsonApiResourceSuccessTransportSchema({
   includeLinks = false,
   includeMeta = false,
   includeIncluded = false,
+  allowSparseFields = false,
   excludeAttributeKeys = [],
   relationshipEntries = []
 } = {}) {
@@ -475,6 +479,7 @@ function createJsonApiResourceSuccessTransportSchema({
     type,
     attributes,
     requireId: true,
+    allowSparseFields,
     excludeAttributeKeys,
     relationshipEntries
   });
@@ -890,6 +895,7 @@ function createJsonApiResourceRouteContract({
   outputKind = "record",
   successStatus = 200,
   includeValidation400 = false,
+  allowSparseFields = false,
   allowBodyId = false,
   pointerPrefix = "/data/attributes",
   bodyAttributeExcludeKeys = [],
@@ -984,6 +990,7 @@ function createJsonApiResourceRouteContract({
         includeLinks: typeof getDocumentLinks === "function",
         includeMeta: typeof getDocumentMeta === "function" || normalizedOutputKind === "collection",
         includeIncluded: typeof getIncluded === "function",
+        allowSparseFields,
         excludeAttributeKeys: outputAttributeExcludeKeys,
         relationshipEntries: outputRelationshipEntries
       })

package/test/jsonApiRouteTransport.test.js

@@ -3,6 +3,7 @@ import test from "node:test";
 
 import {
   JSON_API_CONTENT_TYPE,
+  encodeJsonApiResourceQueryObject,
   createJsonApiResourceQueryTransportSchema,
   createJsonApiResourceRequestBodyTransportSchema,
   createJsonApiResourceRouteContract,
@@ -70,6 +71,17 @@ const CONTACT_LIST_QUERY_SCHEMA = Object.freeze({
       type: "string",
       required: false
     },
+    fields: {
+      type: "object",
+      required: false,
+      values: {
+        type: "array",
+        items: {
+          type: "string",
+          minLength: 1
+        }
+      }
+    },
     workspaceId: {
       type: "string",
       required: false,
@@ -198,6 +210,23 @@ test("createJsonApiResourceQueryTransportSchema and route transport map list que
   assert.ok(Object.hasOwn(schema.properties, "filter[q]"));
   assert.ok(Object.hasOwn(schema.properties, "include"));
   assert.ok(Object.hasOwn(schema.properties, "filter[workspaceId]"));
+  assert.ok(Object.hasOwn(schema.properties, "fields"));
+  assert.ok(Object.hasOwn(schema.patternProperties, "^fields\\[[^\\[\\]]+\\]$"));
+
+  assert.deepEqual(
+    encodeJsonApiResourceQueryObject({
+      fields: {
+        contacts: ["id", "name"],
+        workspaces: ["id", "slug"]
+      }
+    }, {
+      responseType: "contacts"
+    }),
+    {
+      "fields[contacts]": "id,name",
+      "fields[workspaces]": "id,slug"
+    }
+  );
 
   const transport = createJsonApiResourceRouteTransport({
     type: "contacts",
@@ -210,7 +239,9 @@ test("createJsonApiResourceQueryTransportSchema and route transport map list que
     "page[limit]": "10",
     "filter[q]": "Merc",
     include: "workspace",
-    "filter[workspaceId]": "7"
+    "filter[workspaceId]": "7",
+    "fields[contacts]": "id,name",
+    "fields[workspaces]": "id,slug"
   });
 
   assert.deepEqual(plainQuery, {
@@ -218,8 +249,41 @@ test("createJsonApiResourceQueryTransportSchema and route transport map list que
     limit: "10",
     q: "Merc",
     include: "workspace",
-    workspaceId: "7"
+    workspaceId: "7",
+    fields: {
+      contacts: ["id", "name"],
+      workspaces: ["id", "slug"]
+    }
   });
+
+  assert.deepEqual(
+    transport.request.query({
+      fields: "name,id"
+    }),
+    {
+      fields: {
+        contacts: ["id", "name"]
+      }
+    }
+  );
+});
+
+test("sparse JSON:API response contracts preserve field types without requiring every attribute", () => {
+  const schema = createJsonApiResourceSuccessTransportSchema({
+    type: "contacts",
+    attributes: CONTACT_RECORD_SCHEMA,
+    kind: "collection",
+    allowSparseFields: true
+  });
+  const resourceSchema = schema.definitions.contactsSuccessResource;
+  const attributesSchemaName = resourceSchema.properties.attributes.allOf[0].$ref
+    .replace("#/definitions/", "");
+  const attributesSchema = schema.definitions[attributesSchemaName];
+
+  assert.deepEqual(resourceSchema.required, ["type", "id"]);
+  assert.equal(Object.hasOwn(attributesSchema, "required"), false);
+  assert.equal(attributesSchema.additionalProperties, false);
+  assert.equal(attributesSchema.properties.subscribed.anyOf[0].type, "boolean");
 });
 
 test("createJsonApiResourceRouteContract produces route options compatible with kernel route validator", () => {