Missing Changelog for Version 7.x - Unofficial Community Changelog

[amitav13]

Summary

Version 7.x of json-rules-engine represents a major version bump from 6.x, but there is no official changelog documenting the changes. This makes it difficult for users to safely upgrade and understand what breaking changes they need to account for.

The CHANGELOG.md file in the package only goes up to version 6.1.0, leaving versions 6.2.0 through 7.3.1 completely undocumented.

Impact

• Users are hesitant to upgrade due to unknown breaking changes
• Security vulnerability in jsonpath-plus (CVE-2024-21534) requires upgrading to v7+
• Issue version 7 - Design #372 discusses v7 design but doesn't provide a migration guide
• Existing issue about "list of breaking changes v7" shows community need for this information

Unofficial Community Changelog (6.5.0 → 7.3.1)

⚠️ DISCLAIMER: This changelog is based on code comparison and TypeScript definition analysis. It is NOT official and may be incomplete. Users should perform their own testing before upgrading in production environments.

---

🔴 BREAKING CHANGES

1. Node.js Version Requirement

- v6.5.0: No engine requirement
+ v7.x: Requires Node.js >= 18.0.0

2. Security: jsonpath-plus Dependency Updated

- v6.5.0: jsonpath-plus@^7.2.0 (vulnerable to RCE - CVE-2024-21534)
+ v7.x: jsonpath-plus@^10.3.0 (patched)

This is the primary reason to upgrade to v7.

3. Removed Dependency

- v6.5.0: lodash.isobjectlike@^4.0.0
+ v7.x: Removed (replaced with internal implementation)

Impact: Internal change only, should not affect user code

4. API Change: addOperator() Return Type

// v6.5.0
engine.addOperator(operator): Map<string, Operator>

// v7.x
engine.addOperator(operator): void

Impact: Code that uses the return value of addOperator() will break.

Example of breaking code:

// This will break in v7
const operators = engine.addOperator('customOp', callback);
operators.get('customOp'); // ❌ operators is now void

// Instead, operators should be tracked separately
engine.addOperator('customOp', callback); // ✅ Returns void in v7

5. Deprecation: rule.ruleEvent Property

// v6.5.0
rule.event      // ✅ Available

// v7.x
rule.ruleEvent  // ⚠️ Deprecated (still works but shows warning)
rule.event      // ✅ Preferred

Impact: Soft breaking change - existing code using rule.event continues to work

6. Event Handler Type Signature

// v6.5.0
engine.on('success', handler: EventHandler): this
engine.on('failure', handler: EventHandler): this

// v7.x
engine.on<T = Event>(eventName: string, handler: EventHandler<T>): this

Impact: More flexible, backwards compatible for JavaScript users. TypeScript users get better type inference.

---

✨ NEW FEATURES

7. Operator Decorators (Major new feature)

New APIs:

engine.addOperatorDecorator(decorator: OperatorDecorator): void
engine.addOperatorDecorator<A, B, NextA, NextB>(
  decoratorName: string,
  callback: OperatorDecoratorEvaluator<A, B, NextA, NextB>
): void
engine.removeOperatorDecorator(decorator: OperatorDecorator | string): boolean

// New class
class OperatorDecorator {
  constructor(
    name: string,
    evaluator: OperatorDecoratorEvaluator<A, B, NextA, NextB>,
    validator?: (factValue: A) => boolean
  )
}

Allows wrapping operators with additional logic for preprocessing, logging, or custom validation.

New distribution files added:

• dist/operator-decorator.js
• dist/operator-map.js
• dist/engine-default-operator-decorators.js

8. Enhanced Result Types

New TypeScript types for better result handling:

• TopLevelConditionResult
• RuleResultSerializable
• ConditionResultProperties
• BooleanConditionResultProperties
• Various condition result types (AllConditionsResult, AnyConditionsResult, NotConditionsResult, ConditionReferenceResult)

Enhanced RuleResult interface:

interface RuleResult {
  toJSON(): string;
  toJSON<T extends boolean>(stringify: T): T extends true ? string : RuleResultSerializable;
}

---

📝 MIGRATION CHECKLIST

When upgrading from v6.x to v7.x:

1. ✅ Verify Node.js version is >= 18.0.0
2. 🔍 Search codebase for addOperator() usage and remove any code that depends on its return value
3. 🔍 (Optional) Search for rule.ruleEvent and replace with rule.event
4. ⚠️ IMPORTANT: Update Jest/Vitest configs that map jsonpath-plus to use v10.3.0 CommonJS build (see jsonpath-plus expects browser to use ESM #417)
5. 🧪 Run full test suite
6. 🔬 Test in a staging environment before production deployment

Search commands:

# Find addOperator usage
grep -r "addOperator" --include="*.ts" --include="*.js"

# Find deprecated ruleEvent usage
grep -r "\.ruleEvent" --include="*.ts" --include="*.js"

---

⚠️ KNOWN ISSUE: ESM/CommonJS Compatibility (#417)

As reported in Issue #417, jsonpath-plus@10.x serves ESM modules for browsers, but json-rules-engine v7.3.1 only supports CommonJS. This causes issues in browser environments and test runners like Jest/Vitest.

Workaround for Jest/Vitest:

// jest.config.js or vitest.config.js
moduleNameMapper: {
  "^jsonpath-plus$": 
    "<rootDir>/node_modules/.pnpm/jsonpath-plus@10.3.0/node_modules/jsonpath-plus/dist/index-node-cjs.cjs"
}

Impact: If you're running json-rules-engine in browser tests, you'll need to configure your test runner to use the CommonJS build of jsonpath-plus.

---

Request to Maintainers

Could the maintainers please:

1. Update the CHANGELOG.md with official release notes for versions 6.2.0 through 7.3.1
2. Document any breaking changes that were introduced
3. Provide a migration guide from v6 to v7
4. Consider publishing release notes for future versions on the GitHub Releases page

Having an official changelog is crucial for:

• Understanding breaking changes before upgrading
• Planning migration efforts
• Maintaining trust in semantic versioning
• Helping users upgrade safely to get the security fix for jsonpath-plus

The security vulnerability in jsonpath-plus makes upgrading to v7 important, but the lack of documentation makes users hesitant to do so.

---

How This Changelog Was Created

This unofficial changelog was created by:

1. Comparing TypeScript definitions (types/index.d.ts) between v6.5.0 and v7.3.1
2. Analyzing package.json differences (dependencies, engines)
3. Comparing distribution files (dist/ directory)
4. Reviewing Issue #372 for v7 design goals
5. Testing the changes in a real project

⚠️ This is NOT an exhaustive list. There may be additional changes, bug fixes, or subtle behavior differences not captured here.

---

Community Contributions Welcome

If others have found additional breaking changes or differences not listed here, please comment below so we can build a more complete picture of what changed in v7.

---

Related Issues

• version 7 - Design #372 - version 7 - Design
• list of breaking changes v7 #408 - list of breaking changes v7 (community request for changelog)
• jsonpath-plus expects browser to use ESM #417 - jsonpath-plus expects browser to use ESM (ESM/CommonJS compatibility issue)
• fix(deps): update dependency jsonpath-plus to 10.0.0 due to vulnerability #379 - PR: fix(deps): update dependency jsonpath-plus to 10.0.0 due to vulnerability

References

• CVE-2024-21534 - jsonpath-plus RCE vulnerability
• GitHub Advisory Database - jsonpath-plus

---

Community Members: Please add your findings in the comments if you discover additional changes during your upgrade process.

Maintainers: Thank you for this excellent library! An official changelog would be greatly appreciated by the community. 🙏