feat: toDTO method, improved logging, log error when accessing a partial model

Author: ProGM

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node: ["18", "20"]
+        node: ["18", "20", "22"]
     name: Node ${{ matrix.node }} sample
     steps:
       - uses: actions/checkout@v2

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project made by Monade Team are documented in this file. For info refer to team@monade.io
 
+## [2.0.0] - 2025-01-24
+### Added
+- When resolving a model not present in the included array, it returns an error when trying to access it's properties.
+- Added a new method `toDTO` to the `Model` class, that returns a DTO object with the model's properties, replacing relationships with ids.
+- Added a max depth to the `toJSON` method, to avoid infinite loops when serializing relationships.
+
+### Changed
+- BREAKING: the debug now returns a tag (error, warn, info) before the message, allowing to distinguish between error types.
+
 ## [1.1.0] - 2023-09-03
 
 ### Added

dist/index.cjs.js

@@ -2,21 +2,50 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+const $registeredModels = [];
+const $registeredAttributes = [];
+const $registeredRelationships = [];
+
 class Model {
-  toJSON() {
-    return { ...this
+  toDTO() {
+    const response = {
+      ...this
+    };
+    delete response._type;
+    const rels = $registeredRelationships.find(e => e.klass === this.constructor) ?? {
+      attributes: {}
     };
+    for (const key in response) {
+      if (rels.attributes[key] || response[key] instanceof Model) {
+        response[`${key}Id`] = response[key]?.id ?? null;
+        delete response[key];
+      }
+    }
+    return response;
+  }
+  toJSON(maxDepth = 100) {
+    const response = {
+      ...this
+    };
+    delete response._type;
+    for (const key in response) {
+      if (response[key] instanceof Model) {
+        if (maxDepth <= 0) {
+          delete response[key];
+        } else {
+          response[key] = response[key].toJSON(maxDepth - 1);
+        }
+      }
+    }
+    return response;
   }
-
   toFormData() {
     const data = this.toJSON();
     const formData = new FormData();
-
     for (const key in data) {
       if (data[key] === null || data[key] === undefined) {
         continue;
       }
-
       if (Array.isArray(data[key])) {
         for (const value of data[key]) {
           formData.append(key + "[]", value);
@@ -27,47 +56,49 @@ class Model {
         formData.append(key, data[key]);
       }
     }
-
     return formData;
   }
-
 }
 
-function debug(...args) {
-  debug.adapter(...args);
+function debug(level, ...args) {
+  debug.adapter(level, ...args);
 }
-
-debug.adapter = (...args) => console.warn(...args);
+debug.adapter = (level, ...args) => {
+  switch (level) {
+    case 'warn':
+      console.warn(...args);
+      break;
+    case 'error':
+      console.error(...args);
+      break;
+    case 'info':
+    default:
+      console.log(...args);
+      break;
+  }
+};
 
 class Parser {
-  static $registeredModels = [];
-  static $registeredAttributes = [];
-  static $registeredRelationships = [];
   resolved = {};
-
   constructor(data, included = []) {
     this.data = data;
     this.included = included;
   }
-
   run() {
     if (!this.data) {
       return null;
     }
-
     const {
       data,
       included
     } = this;
     const fullIncluded = Array.isArray(data) ? [...data, ...included] : [data, ...included];
     return this.parse(data, fullIncluded);
   }
-
   parse(data, included = []) {
     if (!data) {
       return null;
     }
-
     if (Array.isArray(data)) {
       return this.parseList(data, included);
     } else if ("data" in data && !("id" in data)) {
@@ -76,119 +107,126 @@ class Parser {
       return this.parseElement(data, included);
     }
   }
-
   parseList(list, included) {
     return list.map(e => {
       return this.parseElement(e, included);
     });
   }
-
   parseElement(element, included) {
     const uniqueKey = `${element.id}$${element.type}`;
-
     if (this.resolved[uniqueKey]) {
       return this.resolved[uniqueKey];
     }
-
     const loadedElement = Parser.load(element, included);
-    const model = Parser.$registeredModels.find(e => e.type === loadedElement.type);
-    const attrData = Parser.$registeredAttributes.find(e => e.klass === model?.klass);
-    const relsData = Parser.$registeredRelationships.find(e => e.klass === model?.klass);
-    const instance = new (model?.klass || Model)();
+    const model = $registeredModels.find(e => e.type === loadedElement.type);
+    const instance = this.wrapWhenPartial(new (model?.klass || Model)(), loadedElement);
     this.resolved[uniqueKey] = instance;
+    if (model && model.createFn) {
+      return model.createFn(instance, loadedElement, relation => this.parse(relation, included));
+    }
+    const attrData = $registeredAttributes.find(e => e.klass === model?.klass);
+    const relsData = $registeredRelationships.find(e => e.klass === model?.klass);
     instance.id = loadedElement.id;
-
-    for (const key in loadedElement.attributes) {
-      const parser = attrData?.attributes?.[key];
-
+    instance._type = loadedElement.type;
+    this.parseAttributes(instance, loadedElement, attrData);
+    this.parseRelationships(instance, loadedElement, relsData, included);
+    return instance;
+  }
+  wrapWhenPartial(instance, loadedElement) {
+    if (loadedElement.$_partial) {
+      return new Proxy(instance, {
+        get: function (target, prop) {
+          if (prop in target) {
+            return target[prop];
+          }
+          if (prop === "$_partial") {
+            return true;
+          }
+          debug('error', `Trying to call property "${prop.toString()}" to a model that is not included. Add "${loadedElement.type}" to included models.`);
+          return undefined;
+        }
+      });
+    }
+    return instance;
+  }
+  parseRelationships(instance, loadedElement, relsData, included) {
+    for (const key in loadedElement.relationships) {
+      const relation = loadedElement.relationships[key];
+      const parser = relsData?.attributes?.[key];
       if (parser) {
-        instance[parser.key] = parser.parser(loadedElement.attributes[key]);
+        instance[parser.key] = parser.parser(this.parse(relation, included));
       } else {
-        instance[key] = loadedElement.attributes[key];
-        debug(`Undeclared key "${key}" in "${loadedElement.type}"`);
+        instance[key] = this.parse(relation, included);
+        debug('warn', `Undeclared relationship "${key}" in "${loadedElement.type}"`);
       }
     }
-
-    if (attrData) {
-      for (const key in attrData.attributes) {
-        const parser = attrData.attributes[key];
-
+    if (relsData) {
+      for (const key in relsData.attributes) {
+        const parser = relsData.attributes[key];
         if (!(parser.key in instance)) {
           if ("default" in parser) {
             instance[parser.key] = parser.default;
           } else {
-            debug(`Missing attribute "${key}" in "${loadedElement.type}"`);
+            debug('warn', `Missing relationships "${key}" in "${loadedElement.type}"`);
           }
         }
       }
     }
-
-    for (const key in loadedElement.relationships) {
-      const relation = loadedElement.relationships[key];
-      const parser = relsData?.attributes?.[key];
-
+  }
+  parseAttributes(instance, loadedElement, attrData) {
+    for (const key in loadedElement.attributes) {
+      const parser = attrData?.attributes?.[key];
       if (parser) {
-        instance[parser.key] = parser.parser(this.parse(relation, included));
+        instance[parser.key] = parser.parser(loadedElement.attributes[key]);
       } else {
-        instance[key] = this.parse(relation, included);
-        debug(`Undeclared relationship "${key}" in "${loadedElement.type}"`);
+        instance[key] = loadedElement.attributes[key];
+        debug('warn', `Undeclared key "${key}" in "${loadedElement.type}"`);
       }
     }
-
-    if (relsData) {
-      for (const key in relsData.attributes) {
-        const parser = relsData.attributes[key];
-
+    if (attrData) {
+      for (const key in attrData.attributes) {
+        const parser = attrData.attributes[key];
         if (!(parser.key in instance)) {
           if ("default" in parser) {
             instance[parser.key] = parser.default;
           } else {
-            debug(`Missing relationships "${key}" in "${loadedElement.type}"`);
+            debug('warn', `Missing attribute "${key}" in "${loadedElement.type}"`);
           }
         }
       }
     }
-
-    return instance;
   }
-
   static load(element, included) {
     const found = included.find(e => e.id == element.id && e.type === element.type);
-
     if (!found) {
-      debug(`Relationship with type ${element.type} with id ${element.id} not present in included`);
+      debug('info', `Relationship with type ${element.type} with id ${element.id} not present in included`);
     }
-
-    return found || { ...element,
+    return found || {
+      ...element,
       $_partial: true
     };
   }
-
 }
 
 function Attr(sourceKey, options = {
   parser: v => v
 }) {
   return function _Attr(klass, key) {
-    let model = Parser.$registeredAttributes.find(e => e.klass === klass.constructor);
-
+    let model = $registeredAttributes.find(e => e.klass === klass.constructor);
     if (!model) {
       model = {
         attributes: {},
         klass: klass.constructor
       };
-      Parser.$registeredAttributes.push(model);
+      $registeredAttributes.push(model);
     }
-
     const data = {
       parser: options.parser ?? (v => v),
       key
     };
-
     if ("default" in options) {
       data.default = options.default;
     }
-
     model.attributes[sourceKey ?? key] = data;
   };
 }
@@ -197,16 +235,14 @@ function Rel(sourceKey, options = {
   parser: v => v
 }) {
   return function _Rel(klass, key) {
-    let model = Parser.$registeredRelationships.find(e => e.klass === klass.constructor);
-
+    let model = $registeredRelationships.find(e => e.klass === klass.constructor);
     if (!model) {
       model = {
         attributes: {},
         klass: klass.constructor
       };
-      Parser.$registeredRelationships.push(model);
+      $registeredRelationships.push(model);
     }
-
     model.attributes[sourceKey ?? key] = {
       parser: options.parser ?? (v => v),
       key,
@@ -217,7 +253,7 @@ function Rel(sourceKey, options = {
 
 function JSONAPI(type) {
   return function _JSONAPI(constructor) {
-    Parser.$registeredModels.push({
+    $registeredModels.push({
       klass: constructor,
       type
     });