@jskit-ai/crud-core 0.1.92 → 0.1.93

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.92",
+  version: "0.1.93",
   kind: "runtime",
   description: "Shared CRUD helpers used by CRUD modules.",
   dependsOn: [
@@ -28,7 +28,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/crud-core": "0.1.92"
+        "@jskit-ai/crud-core": "0.1.93"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.92",
+  "version": "0.1.93",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -27,15 +27,15 @@
     "./server/routeContracts": "./src/server/routeContracts.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.84",
-    "@jskit-ai/http-runtime": "0.1.83",
-    "@jskit-ai/kernel": "0.1.84",
+    "@jskit-ai/database-runtime": "0.1.85",
+    "@jskit-ai/http-runtime": "0.1.84",
+    "@jskit-ai/kernel": "0.1.85",
     "json-rest-schema": "1.x.x",
-    "@jskit-ai/realtime": "0.1.83",
-    "@jskit-ai/resource-crud-core": "0.1.29",
-    "@jskit-ai/shell-web": "0.1.83",
-    "@jskit-ai/users-core": "0.1.94",
-    "@jskit-ai/users-web": "0.1.99"
+    "@jskit-ai/realtime": "0.1.84",
+    "@jskit-ai/resource-crud-core": "0.1.30",
+    "@jskit-ai/shell-web": "0.1.84",
+    "@jskit-ai/users-core": "0.1.95",
+    "@jskit-ai/users-web": "0.1.100"
   },
   "peerDependencies": {
     "@tanstack/vue-query": "^5.90.5",

package/src/server/routeContracts.js

@@ -6,6 +6,7 @@ import {
   composeSchemaDefinitions,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
+import { resolveCrudResourceScopeName } from "@jskit-ai/kernel/shared/support/crudLookup";
 import {
   createCrudCursorPaginationQueryValidator,
   listSearchQueryValidator as defaultListSearchQueryValidator,
@@ -33,19 +34,48 @@ function resolveJsonApiRelationshipEntries(definition = null) {
   for (const [fieldKey, fieldDefinition] of Object.entries(resolveSchemaFieldDefinitions(definition))) {
     const normalizedFieldDefinition = isRecord(fieldDefinition) ? fieldDefinition : {};
     const relationshipType = String(normalizedFieldDefinition.belongsTo || "").trim();
-    if (!relationshipType) {
+    if (relationshipType) {
+      const relationshipName = String(normalizedFieldDefinition.as || fieldKey || "").trim();
+      if (!relationshipName) {
+        continue;
+      }
+
+      entries.push(Object.freeze({
+        attributeKey: fieldKey,
+        relationshipName,
+        relationshipType,
+        required: normalizedFieldDefinition.required === true,
+        nullable: normalizedFieldDefinition.nullable === true
+      }));
+      continue;
+    }
+
+    const relation = isRecord(normalizedFieldDefinition.relation)
+      ? normalizedFieldDefinition.relation
+      : {};
+    if (String(relation.kind || "").trim().toLowerCase() !== "collection") {
       continue;
     }
 
-    const relationshipName = String(normalizedFieldDefinition.as || fieldKey || "").trim();
-    if (!relationshipName) {
+    const collectionRelationshipType = resolveCrudResourceScopeName(
+      relation.target || relation.targetResource || relation.namespace || relation.apiPath
+    );
+    if (!collectionRelationshipType) {
+      continue;
+    }
+
+    const collectionRelationshipName = String(
+      relation.as || normalizedFieldDefinition.as || fieldKey || ""
+    ).trim();
+    if (!collectionRelationshipName) {
       continue;
     }
 
     entries.push(Object.freeze({
       attributeKey: fieldKey,
-      relationshipName,
-      relationshipType,
+      relationshipName: collectionRelationshipName,
+      relationshipType: collectionRelationshipType,
+      many: true,
       required: normalizedFieldDefinition.required === true,
       nullable: normalizedFieldDefinition.nullable === true
     }));
@@ -54,6 +84,79 @@ function resolveJsonApiRelationshipEntries(definition = null) {
   return Object.freeze(entries);
 }
 
+function readOwnValue(source = {}, key = "") {
+  if (isRecord(source) && Object.hasOwn(source, key)) {
+    return {
+      found: true,
+      value: source[key]
+    };
+  }
+
+  return {
+    found: false,
+    value: undefined
+  };
+}
+
+function resolveLookupContainer(record = {}, lookupContainerKey = "") {
+  const normalizedLookupContainerKey = String(lookupContainerKey || "").trim();
+  if (!normalizedLookupContainerKey || !isRecord(record?.[normalizedLookupContainerKey])) {
+    return {};
+  }
+
+  return record[normalizedLookupContainerKey];
+}
+
+function resolveRelationshipValueSource(record = {}, entry = {}, {
+  lookupContainerKey = "",
+  preferLookup = false
+} = {}) {
+  const lookups = resolveLookupContainer(record, lookupContainerKey);
+  const lookupValueByAttributeKey = readOwnValue(lookups, entry.attributeKey);
+  const lookupValue = lookupValueByAttributeKey.found
+    ? lookupValueByAttributeKey
+    : readOwnValue(lookups, entry.relationshipName);
+  const recordValue = readOwnValue(record, entry.attributeKey);
+
+  if (preferLookup) {
+    return lookupValue.found ? lookupValue : recordValue;
+  }
+
+  return recordValue.found ? recordValue : lookupValue;
+}
+
+function normalizeLookupId(value) {
+  if (value == null) {
+    return null;
+  }
+
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function normalizeRelationshipIdentifierId(value = null) {
+  if (isRecord(value)) {
+    if (isRecord(value.data)) {
+      return normalizeLookupId(value.data.id);
+    }
+    return normalizeLookupId(value.id);
+  }
+
+  return normalizeLookupId(value);
+}
+
+function createRelationshipIdentifier(entry = {}, value = null) {
+  const id = normalizeRelationshipIdentifierId(value);
+  if (!id) {
+    return null;
+  }
+
+  return {
+    type: entry.relationshipType,
+    id
+  };
+}
+
 function createRecordAttributesResolver(definition = null, {
   excludeKeys = []
 } = {}) {
@@ -91,7 +194,9 @@ function createRecordAttributesResolver(definition = null, {
   };
 }
 
-function createRecordRelationshipsResolver(definition = null) {
+function createRecordRelationshipsResolver(definition = null, {
+  lookupContainerKey = ""
+} = {}) {
   const relationshipEntries = resolveJsonApiRelationshipEntries(definition);
   if (relationshipEntries.length < 1) {
     return null;
@@ -105,18 +210,27 @@ function createRecordRelationshipsResolver(definition = null) {
     const relationships = {};
 
     for (const entry of relationshipEntries) {
-      if (!Object.hasOwn(record, entry.attributeKey)) {
+      const relationshipSource = resolveRelationshipValueSource(record, entry, {
+        lookupContainerKey,
+        preferLookup: entry.many === true
+      });
+      if (!relationshipSource.found) {
+        continue;
+      }
+
+      const value = relationshipSource.value;
+      if (entry.many === true) {
+        const items = Array.isArray(value) ? value : [];
+        relationships[entry.relationshipName] = {
+          data: items
+            .map((item) => createRelationshipIdentifier(entry, item))
+            .filter(Boolean)
+        };
         continue;
       }
 
-      const value = record[entry.attributeKey];
       relationships[entry.relationshipName] = {
-        data: value == null || (typeof value === "string" && value.trim() === "")
-          ? null
-          : {
-              type: entry.relationshipType,
-              id: String(value)
-            }
+        data: createRelationshipIdentifier(entry, value)
       };
     }
 
@@ -145,7 +259,16 @@ function createRequestRelationshipMapper(definition = null) {
       const data = relationship.data;
 
       if (data == null) {
-        mapped[entry.attributeKey] = null;
+        mapped[entry.attributeKey] = entry.many === true ? [] : null;
+        continue;
+      }
+
+      if (entry.many === true) {
+        mapped[entry.attributeKey] = Array.isArray(data)
+          ? data
+              .map((item) => normalizeRelationshipIdentifierId(item))
+              .filter(Boolean)
+          : [];
         continue;
       }
 
@@ -167,15 +290,6 @@ function resolveLookupContainerKey(resource = {}) {
   return String(resource?.contract?.lookup?.containerKey || "").trim();
 }
 
-function normalizeLookupId(value) {
-  if (value == null) {
-    return null;
-  }
-
-  const normalized = String(value).trim();
-  return normalized || null;
-}
-
 function normalizeIncludedLookupRecord(source = null, fallbackId = null) {
   if (!isRecord(source)) {
     return null;
@@ -224,6 +338,41 @@ function normalizeIncludedLookupRecord(source = null, fallbackId = null) {
   };
 }
 
+function appendIncludedRelationshipResource({
+  included = [],
+  seen = new Set(),
+  entry = {},
+  lookupRecord = null,
+  fallbackId = null
+} = {}) {
+  const normalizedLookupRecord = normalizeIncludedLookupRecord(lookupRecord, fallbackId);
+  const includedId = normalizeLookupId(normalizedLookupRecord?.id ?? fallbackId);
+  if (!normalizedLookupRecord || !includedId) {
+    return;
+  }
+
+  const resourceKey = `${entry.relationshipType}:${includedId}`;
+  if (seen.has(resourceKey)) {
+    return;
+  }
+  seen.add(resourceKey);
+
+  const attributes = {
+    ...normalizedLookupRecord
+  };
+  delete attributes.id;
+  delete attributes.type;
+  delete attributes.relationships;
+  delete attributes.links;
+  delete attributes.meta;
+
+  included.push(createJsonApiResourceObject({
+    type: entry.relationshipType,
+    id: includedId,
+    attributes
+  }));
+}
+
 function createLookupIncludedResolver(definition = null, {
   lookupContainerKey = ""
 } = {}) {
@@ -254,36 +403,33 @@ function createLookupIncludedResolver(definition = null, {
         : {};
 
       for (const entry of relationshipEntries) {
-        const relationshipId = normalizeLookupId(record[entry.attributeKey]);
-        const lookupRecord = normalizeIncludedLookupRecord(
-          sourceLookups[entry.attributeKey] ?? sourceLookups[entry.relationshipName],
-          relationshipId
-        );
-        const includedId = normalizeLookupId(lookupRecord?.id ?? relationshipId);
-        if (!lookupRecord || !includedId) {
+        if (entry.many === true) {
+          const relationshipSource = resolveRelationshipValueSource(record, entry, {
+            lookupContainerKey: normalizedLookupContainerKey,
+            preferLookup: true
+          });
+          const lookupRecords = Array.isArray(relationshipSource.value) ? relationshipSource.value : [];
+          for (const lookupRecord of lookupRecords) {
+            appendIncludedRelationshipResource({
+              included,
+              seen,
+              entry,
+              lookupRecord,
+              fallbackId: lookupRecord?.id
+            });
+          }
           continue;
         }
 
-        const resourceKey = `${entry.relationshipType}:${includedId}`;
-        if (seen.has(resourceKey)) {
-          continue;
-        }
-        seen.add(resourceKey);
-
-        const attributes = {
-          ...lookupRecord
-        };
-        delete attributes.id;
-        delete attributes.type;
-        delete attributes.relationships;
-        delete attributes.links;
-        delete attributes.meta;
-
-        included.push(createJsonApiResourceObject({
-          type: entry.relationshipType,
-          id: includedId,
-          attributes
-        }));
+        const relationshipId = normalizeLookupId(record[entry.attributeKey]);
+        const lookupRecord = sourceLookups[entry.attributeKey] ?? sourceLookups[entry.relationshipName];
+        appendIncludedRelationshipResource({
+          included,
+          seen,
+          entry,
+          lookupRecord,
+          fallbackId: relationshipId
+        });
       }
     }
 
@@ -329,15 +475,21 @@ function createCrudJsonApiRouteContracts({
   const viewRecordAttributes = createRecordAttributesResolver(viewOutput, {
     excludeKeys: outputAttributeExcludeKeys
   });
-  const viewRecordRelationships = createRecordRelationshipsResolver(viewOutput);
+  const viewRecordRelationships = createRecordRelationshipsResolver(viewOutput, {
+    lookupContainerKey
+  });
   const createRecordAttributes = createRecordAttributesResolver(createOutput, {
     excludeKeys: outputAttributeExcludeKeys
   });
-  const createRecordRelationships = createRecordRelationshipsResolver(createOutput);
+  const createRecordRelationships = createRecordRelationshipsResolver(createOutput, {
+    lookupContainerKey
+  });
   const patchRecordAttributes = createRecordAttributesResolver(patchOutput, {
     excludeKeys: outputAttributeExcludeKeys
   });
-  const patchRecordRelationships = createRecordRelationshipsResolver(patchOutput);
+  const patchRecordRelationships = createRecordRelationshipsResolver(patchOutput, {
+    lookupContainerKey
+  });
   const createRequestRelationships = createRequestRelationshipMapper(createBody);
   const patchRequestRelationships = createRequestRelationshipMapper(patchBody);
   const viewIncluded = createLookupIncludedResolver(viewOutput, {

package/test/routeContracts.test.js

@@ -244,6 +244,26 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
     }
   ]);
 
+  const lookupOnlyRelationshipDocument = contracts.viewRouteContract.transport.response(returnJsonApiData({
+    id: "contact-3",
+    name: "Charlie",
+    lookups: {
+      owner: {
+        id: "user-8",
+        name: "User Eight"
+      }
+    }
+  }));
+
+  assert.deepEqual(lookupOnlyRelationshipDocument.data.relationships, {
+    owner: {
+      data: {
+        type: "userProfiles",
+        id: "user-8"
+      }
+    }
+  });
+
   const listResponseDocument = contracts.listRouteContract.transport.response(returnJsonApiData({
     items: [
       {
@@ -284,6 +304,112 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
   ]);
 });
 
+test("createCrudJsonApiRouteContracts serializes collection relationships from hydrated lookups", () => {
+  const output = createSchemaDefinition({
+    id: {
+      type: "string",
+      required: true
+    },
+    name: {
+      type: "string",
+      required: true
+    },
+    pets: {
+      type: "array",
+      required: false,
+      relation: {
+        kind: "collection",
+        namespace: "pets",
+        foreignKey: "contactId"
+      }
+    },
+    lookups: {
+      type: "object",
+      required: false
+    }
+  }, "replace");
+  const body = createSchemaDefinition({
+    name: {
+      type: "string",
+      required: true
+    }
+  }, "create");
+  const contracts = createCrudJsonApiRouteContracts({
+    resource: {
+      namespace: "contacts",
+      contract: {
+        lookup: {
+          containerKey: "lookups"
+        }
+      },
+      operations: {
+        view: { output },
+        create: { body, output },
+        patch: { body, output }
+      }
+    }
+  });
+
+  const responseDocument = contracts.viewRouteContract.transport.response(returnJsonApiData({
+    id: "contact-1",
+    name: "Alice",
+    lookups: {
+      pets: [
+        {
+          id: "pet-1",
+          name: "Ada",
+          contactId: "contact-1"
+        },
+        {
+          id: "pet-2",
+          name: "Bert",
+          contactId: "contact-1"
+        }
+      ]
+    }
+  }));
+  const resourceSchema = contracts.viewRouteContract.responses[200].transportSchema.definitions.contactsSuccessResource;
+  const relationshipDataSchema = resourceSchema.properties.relationships.properties.pets.properties.data;
+
+  assert.deepEqual(responseDocument.data.attributes, {
+    name: "Alice"
+  });
+  assert.deepEqual(responseDocument.data.relationships, {
+    pets: {
+      data: [
+        {
+          type: "pets",
+          id: "pet-1"
+        },
+        {
+          type: "pets",
+          id: "pet-2"
+        }
+      ]
+    }
+  });
+  assert.deepEqual(responseDocument.included, [
+    {
+      type: "pets",
+      id: "pet-1",
+      attributes: {
+        name: "Ada",
+        contactId: "contact-1"
+      }
+    },
+    {
+      type: "pets",
+      id: "pet-2",
+      attributes: {
+        name: "Bert",
+        contactId: "contact-1"
+      }
+    }
+  ]);
+  assert.equal(relationshipDataSchema.anyOf[0].type, "array");
+  assert.equal(relationshipDataSchema.anyOf[0].items.properties.type.const, "pets");
+});
+
 test("createCrudJsonApiRouteContracts falls back to recordId params when no route params validator is provided", () => {
   const contracts = createCrudJsonApiRouteContracts({
     resource: createCrudResource()