@jskit-ai/crud-core 0.1.65 → 0.1.66

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.65",
+  version: "0.1.66",
   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.65"
+        "@jskit-ai/crud-core": "0.1.66"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -28,15 +28,15 @@
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/database-runtime": "0.1.57",
-    "@jskit-ai/http-runtime": "0.1.56",
-    "@jskit-ai/kernel": "0.1.57",
+    "@jskit-ai/database-runtime": "0.1.58",
+    "@jskit-ai/http-runtime": "0.1.57",
+    "@jskit-ai/kernel": "0.1.58",
     "json-rest-schema": "1.x.x",
-    "@jskit-ai/realtime": "0.1.56",
-    "@jskit-ai/resource-crud-core": "0.1.2",
-    "@jskit-ai/shell-web": "0.1.56",
-    "@jskit-ai/users-core": "0.1.67",
-    "@jskit-ai/users-web": "0.1.72"
+    "@jskit-ai/realtime": "0.1.57",
+    "@jskit-ai/resource-crud-core": "0.1.3",
+    "@jskit-ai/shell-web": "0.1.57",
+    "@jskit-ai/users-core": "0.1.68",
+    "@jskit-ai/users-web": "0.1.73"
   },
   "peerDependencies": {
     "vue": "^3.5.13",

package/src/server/repositorySupport.js

@@ -341,6 +341,10 @@ function mapRecordRow(row, fieldKeys = [], overrides = {}, { recordIdKeys = [] }
     }
 
     const rawValue = row[columnName];
+    if (rawValue === undefined) {
+      continue;
+    }
+
     if (recordIdKeySet.has(normalizedKey)) {
       const normalizedIdValue = normalizeDbRecordId(rawValue, { fallback: null });
       mapped[normalizedKey] = normalizedIdValue || rawValue;

package/src/server/routeContracts.js

@@ -1,4 +1,7 @@
-import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
+import {
+  createJsonApiResourceObject,
+  createJsonApiResourceRouteContract
+} from "@jskit-ai/http-runtime/shared";
 import {
   composeSchemaDefinitions,
   recordIdParamsValidator
@@ -10,6 +13,284 @@ import {
   createCrudParentFilterQueryValidator
 } from "./listQueryValidators.js";
 
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveSchemaFieldDefinitions(definition = null) {
+  const schema = definition?.schema;
+  if (!schema || typeof schema.getFieldDefinitions !== "function") {
+    return {};
+  }
+
+  const definitions = schema.getFieldDefinitions();
+  return isRecord(definitions) ? definitions : {};
+}
+
+function resolveJsonApiRelationshipEntries(definition = null) {
+  const entries = [];
+
+  for (const [fieldKey, fieldDefinition] of Object.entries(resolveSchemaFieldDefinitions(definition))) {
+    const normalizedFieldDefinition = isRecord(fieldDefinition) ? fieldDefinition : {};
+    const relationshipType = String(normalizedFieldDefinition.belongsTo || "").trim();
+    if (!relationshipType) {
+      continue;
+    }
+
+    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
+    }));
+  }
+
+  return Object.freeze(entries);
+}
+
+function createRecordAttributesResolver(definition = null, {
+  excludeKeys = []
+} = {}) {
+  const relationshipEntries = resolveJsonApiRelationshipEntries(definition);
+  const excludedKeys = new Set(
+    relationshipEntries
+      .map((entry) => String(entry.attributeKey || "").trim())
+      .filter(Boolean)
+  );
+
+  for (const key of excludeKeys) {
+    const normalizedKey = String(key || "").trim();
+    if (normalizedKey) {
+      excludedKeys.add(normalizedKey);
+    }
+  }
+
+  if (excludedKeys.size < 1) {
+    return null;
+  }
+
+  return function getRecordAttributes(record = {}) {
+    if (!isRecord(record)) {
+      return {};
+    }
+
+    const attributes = {
+      ...record
+    };
+    delete attributes.id;
+    for (const key of excludedKeys) {
+      delete attributes[key];
+    }
+    return attributes;
+  };
+}
+
+function createRecordRelationshipsResolver(definition = null) {
+  const relationshipEntries = resolveJsonApiRelationshipEntries(definition);
+  if (relationshipEntries.length < 1) {
+    return null;
+  }
+
+  return function getRecordRelationships(record = {}) {
+    if (!isRecord(record)) {
+      return undefined;
+    }
+
+    const relationships = {};
+
+    for (const entry of relationshipEntries) {
+      if (!Object.hasOwn(record, entry.attributeKey)) {
+        continue;
+      }
+
+      const value = record[entry.attributeKey];
+      relationships[entry.relationshipName] = {
+        data: value == null || (typeof value === "string" && value.trim() === "")
+          ? null
+          : {
+              type: entry.relationshipType,
+              id: String(value)
+            }
+      };
+    }
+
+    return Object.keys(relationships).length > 0 ? relationships : undefined;
+  };
+}
+
+function createRequestRelationshipMapper(definition = null) {
+  const relationshipEntries = resolveJsonApiRelationshipEntries(definition);
+  if (relationshipEntries.length < 1) {
+    return null;
+  }
+
+  return function mapRequestRelationships(relationships = {}) {
+    const source = isRecord(relationships) ? relationships : {};
+    const mapped = {};
+
+    for (const entry of relationshipEntries) {
+      if (!Object.hasOwn(source, entry.relationshipName)) {
+        continue;
+      }
+
+      const relationship = isRecord(source[entry.relationshipName])
+        ? source[entry.relationshipName]
+        : {};
+      const data = relationship.data;
+
+      if (data == null) {
+        mapped[entry.attributeKey] = null;
+        continue;
+      }
+
+      if (isRecord(data) && data.id != null && String(data.id).trim()) {
+        mapped[entry.attributeKey] = data.id;
+      }
+    }
+
+    return mapped;
+  };
+}
+
+function resolveOutputAttributeExcludeKeys(resource = {}) {
+  const lookupContainerKey = String(resource?.contract?.lookup?.containerKey || "").trim();
+  return lookupContainerKey ? Object.freeze([lookupContainerKey]) : Object.freeze([]);
+}
+
+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;
+  }
+
+  const directId = normalizeLookupId(source.id);
+  if (directId) {
+    return {
+      id: directId,
+      ...source
+    };
+  }
+
+  const preferredNestedRecord = normalizeLookupId(fallbackId) && isRecord(source[fallbackId])
+    ? source[fallbackId]
+    : null;
+  if (preferredNestedRecord) {
+    return {
+      id: normalizeLookupId(preferredNestedRecord.id ?? fallbackId),
+      ...preferredNestedRecord
+    };
+  }
+
+  const nestedEntries = Object.entries(source).filter(([, value]) => isRecord(value));
+  if (nestedEntries.length !== 1) {
+    const fallbackRecordId = normalizeLookupId(fallbackId);
+    if (!fallbackRecordId) {
+      return null;
+    }
+
+    return {
+      id: fallbackRecordId,
+      ...source
+    };
+  }
+
+  const [nestedKey, nestedRecord] = nestedEntries[0];
+  const nestedId = normalizeLookupId(nestedRecord.id ?? nestedKey ?? fallbackId);
+  if (!nestedId) {
+    return null;
+  }
+
+  return {
+    id: nestedId,
+    ...nestedRecord
+  };
+}
+
+function createLookupIncludedResolver(definition = null, {
+  lookupContainerKey = ""
+} = {}) {
+  const relationshipEntries = resolveJsonApiRelationshipEntries(definition);
+  const normalizedLookupContainerKey = String(lookupContainerKey || "").trim();
+  if (!normalizedLookupContainerKey || relationshipEntries.length < 1) {
+    return null;
+  }
+
+  return function getIncluded(payload = {}) {
+    const sourceRecords = Array.isArray(payload)
+      ? payload
+      : Array.isArray(payload?.items)
+        ? payload.items
+        : isRecord(payload)
+          ? [payload]
+          : [];
+    const included = [];
+    const seen = new Set();
+
+    for (const record of sourceRecords) {
+      if (!isRecord(record)) {
+        continue;
+      }
+
+      const sourceLookups = isRecord(record[normalizedLookupContainerKey])
+        ? record[normalizedLookupContainerKey]
+        : {};
+
+      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) {
+          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
+        }));
+      }
+    }
+
+    return included;
+  };
+}
+
 function createCrudJsonApiRouteContracts({
   resource = {},
   routeParamsValidator = null,
@@ -33,34 +314,93 @@ function createCrudJsonApiRouteContracts({
       ])
     : recordIdParamsValidator;
   const routeType = resource?.namespace;
+  const viewOutput = resource?.operations?.view?.output;
+  const createBody = resource?.operations?.create?.body;
+  const createOutput = resource?.operations?.create?.output;
+  const patchBody = resource?.operations?.patch?.body;
+  const patchOutput = resource?.operations?.patch?.output;
+  const outputAttributeExcludeKeys = resolveOutputAttributeExcludeKeys(resource);
+  const lookupContainerKey = resolveLookupContainerKey(resource);
+  const viewOutputRelationships = resolveJsonApiRelationshipEntries(viewOutput);
+  const createBodyRelationships = resolveJsonApiRelationshipEntries(createBody);
+  const createOutputRelationships = resolveJsonApiRelationshipEntries(createOutput);
+  const patchBodyRelationships = resolveJsonApiRelationshipEntries(patchBody);
+  const patchOutputRelationships = resolveJsonApiRelationshipEntries(patchOutput);
+  const viewRecordAttributes = createRecordAttributesResolver(viewOutput, {
+    excludeKeys: outputAttributeExcludeKeys
+  });
+  const viewRecordRelationships = createRecordRelationshipsResolver(viewOutput);
+  const createRecordAttributes = createRecordAttributesResolver(createOutput, {
+    excludeKeys: outputAttributeExcludeKeys
+  });
+  const createRecordRelationships = createRecordRelationshipsResolver(createOutput);
+  const patchRecordAttributes = createRecordAttributesResolver(patchOutput, {
+    excludeKeys: outputAttributeExcludeKeys
+  });
+  const patchRecordRelationships = createRecordRelationshipsResolver(patchOutput);
+  const createRequestRelationships = createRequestRelationshipMapper(createBody);
+  const patchRequestRelationships = createRequestRelationshipMapper(patchBody);
+  const viewIncluded = createLookupIncludedResolver(viewOutput, {
+    lookupContainerKey
+  });
+  const createIncluded = createLookupIncludedResolver(createOutput, {
+    lookupContainerKey
+  });
+  const patchIncluded = createLookupIncludedResolver(patchOutput, {
+    lookupContainerKey
+  });
 
   return Object.freeze({
     listRouteContract: createJsonApiResourceRouteContract({
       type: routeType,
       query: listRouteQueryValidator,
-      output: resource?.operations?.view?.output,
-      outputKind: "collection"
+      output: viewOutput,
+      outputKind: "collection",
+      outputAttributeExcludeKeys,
+      outputRelationshipEntries: viewOutputRelationships,
+      getRecordAttributes: viewRecordAttributes,
+      getRecordRelationships: viewRecordRelationships,
+      getIncluded: viewIncluded
     }),
     viewRouteContract: createJsonApiResourceRouteContract({
       type: routeType,
       query: lookupIncludeQueryValidator,
-      output: resource?.operations?.view?.output,
-      outputKind: "record"
+      output: viewOutput,
+      outputKind: "record",
+      outputAttributeExcludeKeys,
+      outputRelationshipEntries: viewOutputRelationships,
+      getRecordAttributes: viewRecordAttributes,
+      getRecordRelationships: viewRecordRelationships,
+      getIncluded: viewIncluded
     }),
     createRouteContract: createJsonApiResourceRouteContract({
       type: routeType,
-      body: resource?.operations?.create?.body,
-      output: resource?.operations?.create?.output,
+      body: createBody,
+      output: createOutput,
       outputKind: "record",
       successStatus: 201,
-      includeValidation400: true
+      includeValidation400: true,
+      bodyRelationshipEntries: createBodyRelationships,
+      outputAttributeExcludeKeys,
+      outputRelationshipEntries: createOutputRelationships,
+      mapRequestRelationships: createRequestRelationships,
+      getRecordAttributes: createRecordAttributes,
+      getRecordRelationships: createRecordRelationships,
+      getIncluded: createIncluded
     }),
     updateRouteContract: createJsonApiResourceRouteContract({
       type: routeType,
-      body: resource?.operations?.patch?.body,
-      output: resource?.operations?.patch?.output,
+      body: patchBody,
+      output: patchOutput,
       outputKind: "record",
-      includeValidation400: true
+      includeValidation400: true,
+      bodyRelationshipEntries: patchBodyRelationships,
+      outputAttributeExcludeKeys,
+      outputRelationshipEntries: patchOutputRelationships,
+      mapRequestRelationships: patchRequestRelationships,
+      getRecordAttributes: patchRecordAttributes,
+      getRecordRelationships: patchRecordRelationships,
+      getIncluded: patchIncluded
     }),
     deleteRouteContract: createJsonApiResourceRouteContract({
       type: routeType,

package/test/repositorySupport.test.js

@@ -126,6 +126,18 @@ test("mapRecordRow remaps rows by key/column pairs", () => {
   });
 });
 
+test("mapRecordRow omits keys whose source column is absent", () => {
+  const row = { some_column: 1 };
+  const mapped = mapRecordRow(row, ["someKey", "virtualField"], {
+    someKey: "some_column",
+    virtualField: "virtual_field"
+  });
+
+  assert.deepEqual(mapped, {
+    someKey: 1
+  });
+});
+
 test("buildWritePayload respects defined keys", () => {
   const payload = buildWritePayload(
     { foo: "bar", missing: true },

package/test/routeContracts.test.js

@@ -4,6 +4,7 @@ import { createSchema } from "json-rest-schema";
 import {
   validateSchemaPayload
 } from "@jskit-ai/kernel/shared/validators";
+import { returnJsonApiData } from "@jskit-ai/http-runtime/shared/validators/jsonApiResult";
 import { createCrudJsonApiRouteContracts } from "../src/server/routeContracts.js";
 
 function createSchemaDefinition(structure = {}, mode = "patch") {
@@ -17,6 +18,11 @@ function createCrudResource() {
   return Object.freeze({
     namespace: "contacts",
     defaultSort: Object.freeze(["-createdAt"]),
+    contract: Object.freeze({
+      lookup: Object.freeze({
+        containerKey: "lookups"
+      })
+    }),
     operations: Object.freeze({
       view: Object.freeze({
         output: createSchemaDefinition({
@@ -24,6 +30,13 @@ function createCrudResource() {
             type: "string",
             required: true
           },
+          ownerUserId: {
+            type: "string",
+            required: false,
+            nullable: true,
+            belongsTo: "userProfiles",
+            as: "owner"
+          },
           contactId: {
             type: "string",
             required: false,
@@ -36,11 +49,22 @@ function createCrudResource() {
           name: {
             type: "string",
             required: true
+          },
+          lookups: {
+            type: "object",
+            required: false
           }
         }, "replace")
       }),
       create: Object.freeze({
         body: createSchemaDefinition({
+          ownerUserId: {
+            type: "string",
+            required: false,
+            nullable: true,
+            belongsTo: "userProfiles",
+            as: "owner"
+          },
           contactId: {
             type: "string",
             required: false,
@@ -60,14 +84,32 @@ function createCrudResource() {
             type: "string",
             required: true
           },
+          ownerUserId: {
+            type: "string",
+            required: false,
+            nullable: true,
+            belongsTo: "userProfiles",
+            as: "owner"
+          },
           name: {
             type: "string",
             required: true
+          },
+          lookups: {
+            type: "object",
+            required: false
           }
         }, "replace")
       }),
       patch: Object.freeze({
         body: createSchemaDefinition({
+          ownerUserId: {
+            type: "string",
+            required: false,
+            nullable: true,
+            belongsTo: "userProfiles",
+            as: "owner"
+          },
           name: {
             type: "string",
             required: false
@@ -78,9 +120,20 @@ function createCrudResource() {
             type: "string",
             required: true
           },
+          ownerUserId: {
+            type: "string",
+            required: false,
+            nullable: true,
+            belongsTo: "userProfiles",
+            as: "owner"
+          },
           name: {
             type: "string",
             required: true
+          },
+          lookups: {
+            type: "object",
+            required: false
           }
         }, "replace")
       })
@@ -109,6 +162,7 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
   assert.equal(contracts.listRouteContract.responses[200].transportSchema.type, "object");
   assert.equal(contracts.createRouteContract.responses[201].transportSchema.type, "object");
   assert.equal(contracts.updateRouteContract.responses[200].transportSchema.type, "object");
+  assert.ok(Object.hasOwn(contracts.viewRouteContract.responses[200].transportSchema.properties, "included"));
   assert.equal(Object.hasOwn(contracts.deleteRouteContract.responses, "204"), false);
   assert.equal(contracts.createRouteContract.body, resource.operations.create.body);
   assert.equal(contracts.updateRouteContract.body, resource.operations.patch.body);
@@ -132,6 +186,102 @@ test("createCrudJsonApiRouteContracts builds default CRUD JSON:API contracts", a
     cursor: "offset:2",
     limit: 25
   });
+
+  const decodedCreateBody = contracts.createRouteContract.transport.request.body({
+    data: {
+      type: "contacts",
+      attributes: {
+        name: "Alice"
+      },
+      relationships: {
+        owner: {
+          data: {
+            type: "userProfiles",
+            id: "user-7"
+          }
+        }
+      }
+    }
+  });
+
+  assert.deepEqual(decodedCreateBody, {
+    name: "Alice",
+    ownerUserId: "user-7"
+  });
+
+  const responseDocument = contracts.viewRouteContract.transport.response(returnJsonApiData({
+    id: "contact-1",
+    ownerUserId: "user-7",
+    name: "Alice",
+    lookups: {
+      owner: {
+        "user-7": {
+          id: "user-7",
+          name: "User Seven"
+        }
+      }
+    }
+  }));
+
+  assert.deepEqual(responseDocument.data.attributes, {
+    name: "Alice"
+  });
+  assert.deepEqual(responseDocument.data.relationships, {
+    owner: {
+      data: {
+        type: "userProfiles",
+        id: "user-7"
+      }
+    }
+  });
+  assert.deepEqual(responseDocument.included, [
+    {
+      type: "userProfiles",
+      id: "user-7",
+      attributes: {
+        name: "User Seven"
+      }
+    }
+  ]);
+
+  const listResponseDocument = contracts.listRouteContract.transport.response(returnJsonApiData({
+    items: [
+      {
+        id: "contact-1",
+        ownerUserId: "user-7",
+        name: "Alice",
+        lookups: {
+          owner: {
+            "user-7": {
+              id: "user-7",
+              name: "User Seven"
+            }
+          }
+        }
+      },
+      {
+        id: "contact-2",
+        ownerUserId: "user-7",
+        name: "Bob",
+        lookups: {
+          ownerUserId: {
+            id: "user-7",
+            name: "User Seven"
+          }
+        }
+      }
+    ]
+  }));
+
+  assert.deepEqual(listResponseDocument.included, [
+    {
+      type: "userProfiles",
+      id: "user-7",
+      attributes: {
+        name: "User Seven"
+      }
+    }
+  ]);
 });
 
 test("createCrudJsonApiRouteContracts falls back to recordId params when no route params validator is provided", () => {