@appweaver/core 1.4.0 → 1.4.1

package/export/export-service.js

@@ -99,6 +99,12 @@ class ExportService {
                 // Skip mapping for non-exposed fields.
                 continue;
             }
+            // The records are read from the database rather than through a response
+            // schema, so the fields no response carries are dropped here instead.
+            if (modelSchema?.['hidden'] === true ||
+                resourceModel.config.virtual?.[key]?.output?.type === 'none') {
+                continue;
+            }
             let header = parentKey ? `${parentKey}.${key}` : key;
             const isArrayValue = (0, common_1.isArray)(value);
             const exportField = exportConfig?.[key];

package/factory/create-model.js

@@ -50,6 +50,7 @@ function buildModel(config) {
     const createModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Composite([scalarsSchema, virtualSchema]), config), config.create);
     const updateModel = omitOrPickScalars(resolveDefaultScalars(typebox_1.Type.Partial(typebox_1.Type.Composite([scalarsSchema, virtualSchema])), config), config.update);
     const { readOneModel, readManyModel } = buildOutputModels(baseReadModel, relationsModel, filesModel, config);
+    const readOneNullableModel = buildNullableOutputModel(name);
     const { createOneModel, updateOneModel, relationCreateModel, relationUpdateModel, relationInputModel } = buildInputModels(createModel, updateModel, relationsModel, idSchema, config);
     const { fileUploadModel, fileDeleteModel } = buildFileInputModels(config);
     const resourceModel = {
@@ -64,6 +65,7 @@ function buildModel(config) {
         virtualModel,
         readOneModel,
         readManyModel,
+        readOneNullableModel,
         createOneModel,
         updateOneModel,
         relationCreateModel,
@@ -223,6 +225,17 @@ function buildOutputModels(readModel, relationsModel, filesModel, config) {
     ], { $id: `${config.name}Multiple` });
     return { readOneModel, readManyModel };
 }
+function buildNullableOutputModel(name) {
+    // Builds the nullable variant of the single read model, registered under its own
+    // name so a nullable relation can reference it instead of inlining the union.
+    // The response serializer cannot compile an inline `anyOf` union that cycles
+    // back to a model it is already writing, since it expands every union branch
+    // into a fresh schema. A union behind a name is expanded once and reused, which
+    // keeps a self-referencing relation (a category and its parent) serializable.
+    return typebox_1.Type.Union([typebox_1.Type.Ref(`${name}Single`), typebox_1.Type.Null()], {
+        $id: `${name}SingleNullable`
+    });
+}
 function buildInputModels(createModel, updateModel, relationsModel, idSchema, config) {
     const virtualConfig = config.virtual;
     const relationsConfig = config.relations;
@@ -349,7 +362,7 @@ function relationOutputProperties(object, relationConfig, outputType) {
                 return undefined;
             }
             if (config.required === false && schema.type !== 'array') {
-                schema = (0, common_1.Nullable)(schema);
+                schema = nullableOutputSchema(schema);
             }
         }
         return schema;
@@ -378,6 +391,10 @@ function relationOutputProperties(object, relationConfig, outputType) {
         }, {})
     });
 }
+function nullableOutputSchema(schema) {
+    const modelRef = schema.$ref;
+    return modelRef ? typebox_1.Type.Ref(`${modelRef}Nullable`) : (0, common_1.Nullable)(schema);
+}
 function removeHiddenFields(schema) {
     const properties = {};
     for (const [name, field] of Object.entries(schema.properties)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/core",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Appweaver - the backend framework for AI-first development (@core)",
   "author": "Luka Matosevic",
   "license": "MIT",

package/resource/utils/relation-util.js

@@ -9,6 +9,9 @@ const common_1 = require("@appweaver/common");
 const context_1 = require("../../context");
 const security_1 = require("../../security");
 const errors_1 = require("../../errors");
+/** Levels of a self referencing relation read when the relation configures no
+ * `maxDepth`, i.e. the relation itself and nothing below it. */
+const DEFAULT_RELATION_MAX_DEPTH = 1;
 /**
  * Builds the Prisma `include` clause for the relation and file fields of a resource model. A field is included when
  * its configured output type allows it for the given action, or always when no action is specified, and the relations
@@ -41,7 +44,7 @@ function mapRelationInclusions(resourceName, action) {
         }
         // Check if the relation should be included based on the output type
         if (shouldIncludeRelation(relationField?.output?.type, action)) {
-            inclusion[key] = buildNestedInclusion(relationField, action);
+            inclusion[key] = buildNestedInclusion(relationField, key, action);
         }
     }
     return inclusion;
@@ -294,34 +297,67 @@ function createdByConnect(resourceName) {
         : undefined;
 }
 /**
- * Resolves the inclusion value of a single relation field by walking its configured nested output includes
- * recursively. Returns `true` when the relation has no nested includes to apply for the given action, or a nested
- * `include` clause otherwise.
+ * Resolves the inclusion value of a single relation field, walking both the levels a self referencing relation
+ * repeats itself for and the nested includes it configures. Returns `true` when the relation reads no further than
+ * itself for the given action, or a nested `include` clause otherwise.
+ *
+ * A relation whose related model holds the same relation again points back at its own model, so it repeats itself
+ * down the tree up to its configured `output.maxDepth`, letting a category carry its ancestors without every level
+ * being spelled out. An `output.include` entry naming that same relation configures the level itself and replaces
+ * the repetition.
  *
  * @param {RelationField} relationField - The configuration of the relation whose inclusion value is resolved, read
- * from its `output.include` property.
+ * from its `output.include` and `output.maxDepth` properties.
+ * @param {string} key - The field name the relation is declared under, matched against the related model to detect a
+ * relation pointing back at its own model.
  * @param {ActionType} [action] - The action the inclusions are built for, matched against the configured output type
  * of every nested relation.
- * @return {boolean|Object} True if the relation has no nested relations to include for the given action, or the
- * nested `include` clause otherwise.
+ * @param {number} [depth=1] - The level of the relation being resolved, counting the relation itself as the first.
+ * @return {boolean|Object} True if the relation reads no further than itself, or the nested `include` clause
+ * otherwise.
  */
-function buildNestedInclusion(relationField, action) {
+function buildNestedInclusion(relationField, key, action, depth = 1) {
     const nestedIncludeConfig = relationField?.output?.include;
-    if (!nestedIncludeConfig || Object.keys(nestedIncludeConfig).length === 0) {
-        return true;
-    }
     const nestedInclusion = {};
-    for (const [nestedKey, nestedOutput] of Object.entries(nestedIncludeConfig)) {
+    // A file field carries no related model, so it reads no further than itself
+    const relatedModel = relationField?.model
+        ? (0, context_1.injectModel)((0, common_1.capitalize)(relationField.model), false)
+        : undefined;
+    const selfRelation = selfReferencingRelation(relatedModel, key);
+    const maxDepth = relationField?.output?.maxDepth ?? DEFAULT_RELATION_MAX_DEPTH;
+    if (selfRelation && depth < maxDepth && !nestedIncludeConfig?.[key]) {
+        nestedInclusion[key] = buildNestedInclusion({ ...selfRelation, output: relationField.output }, key, action, depth + 1);
+    }
+    for (const [nestedKey, nestedOutput] of Object.entries(nestedIncludeConfig ?? {})) {
         // Check if the nested relation should be included
-        if (shouldIncludeRelation(nestedOutput?.type, action)) {
-            // Recursively build nested inclusions
-            nestedInclusion[nestedKey] = buildNestedInclusion({ output: nestedOutput }, action);
+        if (!shouldIncludeRelation(nestedOutput?.type, action)) {
+            continue;
         }
+        // The related model carries the field the nested include names, so each
+        // level is resolved against the model it actually belongs to
+        const nestedRelation = relatedModel?.config?.relations?.[nestedKey] ??
+            relatedModel?.config?.files?.[nestedKey];
+        nestedInclusion[nestedKey] = buildNestedInclusion({ ...nestedRelation, output: nestedOutput }, nestedKey, action);
     }
     return Object.keys(nestedInclusion).length > 0
         ? { include: nestedInclusion }
         : true;
 }
+/**
+ * Reads the relation a related model holds under the given field name, when it points back at that same model. It is
+ * the relation a self referencing field repeats itself through, i.e. the `parent` of the parent of a category.
+ *
+ * @param {ResourceModel} [model] - The related model the field is looked up on.
+ * @param {string} key - The field name of the relation.
+ * @return {RelationField | undefined} The relation of the model under that name when it references the model itself,
+ * undefined otherwise.
+ */
+function selfReferencingRelation(model, key) {
+    const relation = key ? model?.config?.relations?.[key] : undefined;
+    return relation && (0, common_1.capitalize)(relation.model) === model?.name
+        ? relation
+        : undefined;
+}
 /**
  * Decides whether a relation with the given configured output type is included for the given action. The `none` type
  * is never included, the `single` type is excluded from the query action, and the `multiple` type is only included on

package/server/swagger.js

@@ -11,7 +11,7 @@ const context_1 = require("../context");
 exports.default = (0, fastify_plugin_1.default)((server) => {
     server.register(swagger_1.default, {
         hideUntagged: common_1.config.SWAGGER_HIDE_UNTAGGED,
-        transformObject: (document) => addConfig(normalizeUnionTypes(pruneUnusedSchemas(document))),
+        transformObject: (document) => addConfig(normalizeUnionTypes(pruneUnusedSchemas(inlineNullableRefs(document)))),
         openapi: {
             info: {
                 title: common_1.config.APP_NAME,
@@ -64,6 +64,54 @@ exports.default = (0, fastify_plugin_1.default)((server) => {
         });
     }
 });
+/**
+ * Replaces every reference to a nullable model variant with the union it stands
+ * for. Each model registers a `<Model>SingleNullable` schema the response
+ * serializer needs as a name of its own, since it cannot compile an inline
+ * union that cycles back to a model it is already writing. The document says
+ * the same thing without that indirection, leaving the variants unreferenced
+ * for {@link pruneUnusedSchemas} to drop.
+ *
+ * @param {Object} document The transform argument of the Swagger plugin,
+ * wrapping the OpenAPI document in its `openapiObject` property.
+ * @returns {Object} The same argument, with every reference to a nullable model
+ * variant replaced in place.
+ */
+function inlineNullableRefs(document) {
+    const schemas = document.openapiObject?.components?.schemas ?? {};
+    // The schemas are registered under generated names, so the variants are
+    // recognized by the title carrying the name they were declared with
+    const variants = new Map();
+    for (const [name, schema] of Object.entries(schemas)) {
+        if (/SingleNullable$/.test(schema?.title ?? '') && (0, common_1.isArray)(schema?.anyOf)) {
+            variants.set(`#/components/schemas/${name}`, schema.anyOf);
+        }
+    }
+    if (variants.size === 0) {
+        return document;
+    }
+    const visit = (node) => {
+        if (!node || typeof node !== 'object') {
+            return;
+        }
+        if ((0, common_1.isArray)(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        for (const value of Object.values(node)) {
+            visit(value);
+        }
+        const union = variants.get(node.$ref);
+        if (union) {
+            delete node.$ref;
+            node.anyOf = structuredClone(union);
+        }
+    };
+    visit(document.openapiObject?.paths);
+    visit(schemas);
+    return document;
+}
 /**
  * Rewrites the JSON Schema type lists of the document into the equivalent
  * `anyOf` unions. The query filter schemas declare their plain values as a