@ealforque/sequelize-field-parser 1.0.4 → 1.0.5

package/README.md

@@ -9,11 +9,17 @@ A TypeScript utility for Sequelize models that lets users specify fields to incl
 
 ## Features
 
-- Parse Sequelize model fields and relationships
-- Generate field trees for complex models
-- Type-safe interfaces and types
-- Easy integration with MySQL via Sequelize
-- Test-driven development with Jest
+- **Parse Sequelize model fields and relationships:** Easily extract and validate fields and associations from models
+- **Generate field trees for complex models:** Build nested relationship trees for Sequelize includes
+- **Type-safe interfaces and types:** All parsing and tree generation is type-safe
+- **Easy integration with MySQL via Sequelize:** Works seamlessly with Sequelize ORM
+- **Test-driven development with Jest:** Comprehensive test suite for robust behavior
+- **Handles maximum relationship depth (default: 10):** Prevents runaway includes and logs warnings
+- **Detects and prevents circular relationships:** Safely handles circular model associations
+- **Handles malformed input:** Catches empty, whitespace, consecutive dots, leading/trailing dots
+- **Deduplicates columns:** Duplicate fields in the input string will not result in duplicate entries in the `columns` array
+- **Model requirements:** Models must define static `DEFAULT_FIELDS` and `SELECTABLE_FIELDS` properties. If these are missing, no fields will be selectable and all user-specified fields may be reported as invalid.
+- **Input requirements:** Only valid Sequelize model classes or objects with the required static properties should be passed. Passing a non-model or incorrectly typed object may result in type errors or runtime errors.
 
 ## Installation
 
@@ -21,42 +27,201 @@ A TypeScript utility for Sequelize models that lets users specify fields to incl
 npm install @ealforque/sequelize-field-parser
 ```
 
-## Usage
+## Usage (Correct Example)
 
-Import and use in your project:
+```typescript
+import FieldParserService from "./src/field_parser.service";
+import SomeModel from "./models/SomeModel";
+
+const parser = new FieldParserService();
+const result = parser.parseFields("id,name,profile.email", SomeModel);
+console.log(result);
+/*
+{
+  columns: ['id', 'name'],
+  relationshipTree: { profile: { email: true } },
+  invalidFields: []
+}
+*/
+```
+
+---
+
+## Edge Case Handling
+
+### Malformed Input
 
 ```typescript
-import FieldParserService from "sequelize-field-parser";
-import Status from "./path/to/status.model";
+const parser = new FieldParserService();
+const result = parser.parseFields(" ,foo..bar,.baz,", SomeModel);
+console.log(result); // invalidFields will include malformed entries
+/*
+{
+  columns: [],
+  relationshipTree: {},
+  invalidFields: ['foo..bar', '.baz']
+}
+*/
+```
+
+### Missing Static Properties
 
+```typescript
 const parser = new FieldParserService();
+const result = parser.parseFields("id,name", ModelWithoutStatics);
+console.log(result); // columns will be empty, invalidFields will include all
+/*
+{
+  columns: [],
+  relationshipTree: {},
+  invalidFields: ['id', 'name']
+}
+*/
+```
 
-// query parameter
-// api/resource?fields='status.uuid,status.name,status.category.uuid,status.category.name'
-const queryParams =
-  "status.uuid,status.name,status.category.uuid,status.category.name";
+### Non-Model Input
 
-// Parse the query parameter
-const { columns, relationshipTree } = parser.parseFields(queryParams, Model);
+```typescript
+const parser = new FieldParserService();
+const result = parser.parseFields("id,name", {});
+console.log(result); // columns empty, invalidFields includes all
+/*
+{
+  columns: [],
+  relationshipTree: {},
+  invalidFields: ['id', 'name']
+}
+*/
+```
+
+### Non-Existent Associations
+
+```typescript
+const parser = new FieldParserService();
+const result = parser.parseFields("profile.address.zip", SomeModel);
+console.log(result); // invalidFields includes non-existent associations
+/*
+{
+  columns: [],
+  relationshipTree: {},
+  invalidFields: ['profile.address.zip']
+}
+*/
+```
 
-// Build the sequelize include
-const include = parser.buildSequelizeInclude(relationshipTree, Model);
+### Deeply Nested/Circular Relationships
 
-console.log(include);
-/* Example output:
+```typescript
+const parser = new FieldParserService();
+const result = parser.parseFields("a.b.c.d.e.f.g.h.i.j.k", SomeModel);
+console.log(result); // invalidFields includes overly deep/circular fields
+/*
+{
+  columns: [],
+  relationshipTree: {},
+  invalidFields: ['a.b.c.d.e.f.g.h.i.j.k']
+}
+*/
+```
+
+### Duplicate Fields
+
+```typescript
+const parser = new FieldParserService();
+const result = parser.parseFields("id,id,name,name", SomeModel);
+console.log(result); // columns deduplicated
+/*
+{
+  columns: ['id', 'name'],
+  relationshipTree: {},
+  invalidFields: []
+}
+*/
+```
+
+### Relationship Leaf Attribute Filtering
+
+If a nested relationship contains attributes not in `SELECTABLE_FIELDS`, those attributes are filtered out and a warning is logged for each ignored attribute.
+
+```typescript
+const parser = new FieldParserService();
+const tree = {
+  status: {
+    name: true,
+    invalid_field: true,
+  },
+};
+const mockModel = {
+  associations: {
+    status: {
+      target: { SELECTABLE_FIELDS: ["name"] },
+    },
+  },
+};
+const result = parser.buildSequelizeInclude(tree, mockModel);
+console.log(result);
+/*
+Warning: FieldParserService: Attribute 'invalid_field' in relationship 'status' is not in SELECTABLE_FIELDS and will be ignored.
+[
+  {
+    model: { SELECTABLE_FIELDS: ["name"] },
+    as: "status",
+    attributes: ["name"],
+    include: [],
+  },
+]
+*/
+```
+
+### Empty Relationship Attributes (No DEFAULT_FIELDS)
+
+If a relationship is specified but no attributes are selected and the related model does not define `DEFAULT_FIELDS`, a warning is logged and the attributes array will be empty.
+
+```typescript
+const parser = new FieldParserService();
+const tree = {
+  status: {}, // No attributes selected
+};
+const mockModel = {
+  associations: {
+    status: {
+      target: { SELECTABLE_FIELDS: [] }, // No DEFAULT_FIELDS
+    },
+  },
+};
+const result = parser.buildSequelizeInclude(tree, mockModel);
+console.log(result);
+/*
+Warning: FieldParserService: No attributes selected and no DEFAULT_FIELDS available for relationship 'status'. Attributes array will be empty.
 [
   {
-    model: Status,
-    as: 'status',
-    attributes: ['uuid', 'name'],
-    include: [
-      {
-        model: Category,
-        as: 'category',
-        attributes: ['uuid', 'name'],
-      }
-    ]
-  }
+    model: { SELECTABLE_FIELDS: [] },
+    as: "status",
+    attributes: [],
+    include: [],
+  },
 ]
 */
 ```
+
+### Association Alias Mismatches
+
+If the association alias in the model does not match the field string, the relationship will not be included and a warning is logged.
+
+```typescript
+const parser = new FieldParserService();
+const mockModel = {
+  associations: {}, // No 'profile' association
+  SELECTABLE_FIELDS: ["id", "name"],
+};
+const result = parser.parseFields("profile.email", mockModel);
+console.log(result);
+/*
+Warning: FieldParserService: Association alias 'profile' does not exist in model 'unknown'. Field 'profile.email' will be treated as invalid.
+{
+  columns: [],
+  relationshipTree: {},
+  invalidFields: ["profile.email"]
+}
+*/
+```

package/dist/field_parser.service.d.ts

@@ -7,7 +7,8 @@ declare class FieldParserService {
     parseFields: <M extends Model>(fields: string, model: ModelStaticWithFields<M>) => {
         columns: string[];
         relationshipTree: RelationshipTree;
+        invalidFields: string[];
     };
-    buildSequelizeInclude: <M extends Model>(tree: RelationshipTree, model: ModelStatic<M>) => IncludeOptions[];
+    buildSequelizeInclude: <M extends Model>(tree: RelationshipTree, model: ModelStatic<M>, depth?: number, visitedModels?: Set<any>) => IncludeOptions[];
 }
 export default FieldParserService;

package/dist/field_parser.service.js

@@ -6,37 +6,100 @@ class FieldParserService {
         this.fields = [];
     }
     parseFields = (fields, model) => {
+        if (typeof model !== "object" ||
+            model === null ||
+            !("associations" in model) ||
+            typeof model.associations !== "object") {
+            console.warn("FieldParserService: Input is not a valid Sequelize model. Returning all fields as invalid.");
+            const inputFields = fields
+                .split(",")
+                .map((f) => f.trim())
+                .filter((f) => f.length > 0);
+            return {
+                columns: [],
+                relationshipTree: {},
+                invalidFields: inputFields,
+            };
+        }
         this.fields = fields
             .split(",")
             .map((f) => f.trim())
             .filter((f) => f.length > 0);
         const relationshipTree = {};
-        const columns = [...model.DEFAULT_FIELDS];
-        const selectableFields = model.SELECTABLE_FIELDS;
+        const invalidFields = [];
+        const safeModel = model;
+        const columns = Array.isArray(safeModel.DEFAULT_FIELDS)
+            ? [...safeModel.DEFAULT_FIELDS]
+            : [];
+        const selectableFields = Array.isArray(safeModel.SELECTABLE_FIELDS)
+            ? safeModel.SELECTABLE_FIELDS
+            : [];
         for (const field of this.fields) {
+            // Basic validation to catch empty fields, fields with only whitespace, and invalid dot usage
+            if (field === "" ||
+                /^\s*$/.test(field) ||
+                /\.\./.test(field) ||
+                /^\.|\.$/.test(field)) {
+                invalidFields.push(field);
+                continue;
+            }
             const segments = field.split(".");
             if (segments.length === 1) {
                 const topField = segments[0];
                 if (selectableFields.includes(topField)) {
                     columns.push(topField);
                 }
+                else {
+                    invalidFields.push(field);
+                }
             }
             else {
                 let relationship = relationshipTree;
+                let currentModel = model;
+                let valid = true;
                 for (let i = 0; i < segments.length; i++) {
-                    const field = segments[i];
-                    if (!relationship[field]) {
-                        relationship[field] = i === segments.length - 1 ? true : {};
+                    const seg = segments[i];
+                    if (i < segments.length - 1) {
+                        if (!currentModel.associations || !currentModel.associations[seg]) {
+                            console.warn(`FieldParserService: Association alias '${seg}' does not exist in model '${currentModel.name || "unknown"}'. Field '${field}' will be treated as invalid.`);
+                            valid = false;
+                            break;
+                        }
+                        currentModel = currentModel.associations[seg].target;
+                        if (!relationship[seg]) {
+                            relationship[seg] = {};
+                        }
+                        relationship = relationship[seg];
                     }
-                    if (relationship[field] !== true) {
-                        relationship = relationship[field];
+                    else {
+                        if (currentModel.SELECTABLE_FIELDS &&
+                            currentModel.SELECTABLE_FIELDS.includes(seg)) {
+                            relationship[seg] = true;
+                        }
+                        else {
+                            valid = false;
+                        }
                     }
                 }
+                if (!valid) {
+                    invalidFields.push(field);
+                }
             }
         }
-        return { columns, relationshipTree };
+        const uniqueColumns = Array.from(new Set(columns));
+        return { columns: uniqueColumns, relationshipTree, invalidFields };
     };
-    buildSequelizeInclude = (tree, model) => {
+    buildSequelizeInclude = (tree, model, depth = 0, visitedModels = new Set()) => {
+        const MAX_DEPTH = 10;
+        if (depth > MAX_DEPTH) {
+            console.warn("Maximum include depth exceeded.");
+            return [];
+        }
+        if (visitedModels.has(model)) {
+            console.warn("Circular relationship detected.");
+            return [];
+        }
+        visitedModels.add(model);
         const includeOptions = Object.entries(tree).flatMap(([relation, nested]) => {
             const relationship = model.associations?.[relation];
             if (!relationship || !relationship.target)
@@ -50,18 +113,34 @@ class FieldParserService {
                     attributes: [],
                 };
             }
-            const deeperIncludes = this.buildSequelizeInclude(nested, currentModel);
+            const deeperIncludes = this.buildSequelizeInclude(nested, currentModel, depth + 1, visitedModels);
             const leafAttributes = Object.entries(nested)
                 .filter(([, value]) => value === true)
-                .map(([key]) => key)
-                .filter((attr) => selectableFields.includes(attr));
+                .map(([key]) => key);
+            const filteredLeafAttributes = leafAttributes.filter((attr) => {
+                const isSelectable = selectableFields.includes(attr);
+                if (!isSelectable) {
+                    console.warn(`FieldParserService: Attribute '${attr}' in relationship '${relation}' is not in SELECTABLE_FIELDS and will be ignored.`);
+                }
+                return isSelectable;
+            });
+            let attributesToUse = filteredLeafAttributes;
+            if (attributesToUse.length === 0) {
+                if (Array.isArray(currentModel.DEFAULT_FIELDS)) {
+                    attributesToUse = [...currentModel.DEFAULT_FIELDS];
+                }
+                else {
+                    console.warn(`FieldParserService: No attributes selected and no DEFAULT_FIELDS available for relationship '${relation}'. Attributes array will be empty.`);
+                }
+            }
             return {
                 model: currentModel,
                 as: relation,
-                attributes: leafAttributes,
+                attributes: attributesToUse,
                 include: deeperIncludes,
             };
         });
+        visitedModels.delete(model);
         return includeOptions;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ealforque/sequelize-field-parser",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "main": "dist/field_parser.service.js",
   "types": "dist/field_parser.service.d.ts",
   "files": [