@ealforque/sequelize-field-parser 1.0.4 → 1.0.6

package/README.md

@@ -2,6 +2,8 @@
 
 ![npm version](https://img.shields.io/npm/v/@ealforque/sequelize-field-parser)
 ![build](https://github.com/ealforque/sequelize-field-parser/actions/workflows/release.yaml/badge.svg)
+![license](https://img.shields.io/badge/license-MIT-green)
+[![Socket Badge](https://badge.socket.dev/npm/package/@ealforque/sequelize-field-parser)](https://badge.socket.dev/npm/package/@ealforque/sequelize-field-parser)
 
 ## Description
 
@@ -9,11 +11,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 +29,212 @@ 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
+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']
+}
+*/
+```
+
+### Non-Model Input
+
+```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']
+}
+*/
+```
+
+### Deeply Nested/Circular Relationships
 
 ```typescript
-import FieldParserService from "sequelize-field-parser";
-import Status from "./path/to/status.model";
+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: []
+}
+*/
+```
 
-// 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";
+### Relationship Leaf Attribute Filtering
 
-// Parse the query parameter
-const { columns, relationshipTree } = parser.parseFields(queryParams, Model);
+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: [],
+  },
+]
+*/
+```
 
-// Build the sequelize include
-const include = parser.buildSequelizeInclude(relationshipTree, Model);
+### Empty Relationship Attributes (No DEFAULT_FIELDS)
 
-console.log(include);
-/* Example output:
+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"]
+}
+*/
+```
+
+## Supply Chain Security
+
+This package runs `npm audit` in its CI workflow to check for vulnerabilities in dependencies before publishing. Automated dependency updates and vulnerability checks are enabled for maximum supply chain security.
+
+Example GitHub Actions step:
+
+```yaml
+- name: Audit dependencies
+  run: npm audit --audit-level=high
+```

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.6",
   "main": "dist/field_parser.service.js",
   "types": "dist/field_parser.service.d.ts",
   "files": [
@@ -17,22 +17,23 @@
     "access": "public"
   },
   "dependencies": {
-    "sequelize": "^6.0.0"
+    "sequelize": "6.0.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "eslint": "^9.26.0",
-    "eslint-config-prettier": "^10.1.3",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "http-status-codes": "^2.3.0",
-    "jest": "^29.7.0",
-    "prettier": "^3.5.3",
-    "sequelize-cli": "^6.6.2",
-    "supertest": "^7.1.0",
-    "ts-jest": "^29.3.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.0"
-  }
+    "@types/jest": "29.5.14",
+    "eslint": "9.26.0",
+    "eslint-config-prettier": "10.1.3",
+    "eslint-plugin-import": "2.31.0",
+    "eslint-plugin-simple-import-sort": "12.1.1",
+    "http-status-codes": "2.3.0",
+    "jest": "29.7.0",
+    "prettier": "3.5.3",
+    "sequelize-cli": "6.6.2",
+    "supertest": "7.1.0",
+    "ts-jest": "29.3.2",
+    "ts-node": "10.9.2",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.32.0"
+  },
+  "license": "MIT"
 }