feat: upgrade to Ajv v8 for v3.0.0-rc.1

[marioburatto]

PR Description

Summary

This PR upgrades the project to Ajv v8 and updates the minimum Node.js version to 24, representing a major version bump to v3.0.0-rc.1. This upgrade includes breaking changes to validation error messages, dependency updates, and modernized CI/CD infrastructure.

Changes

Breaking Changes

• Upgraded Ajv from v6 to v8 — All validation error messages changed from "should" to "must" (e.g., "should be string" → "must be string")
• Validation error ordering — Error order may differ from v2 (e.g., required errors may appear before additionalProperties)
• Custom keyword API changes — ajv-keywords v5 has different schemaPath and params format for sub-keyword errors
• ESLint v8 → v10 — Requires new flat config format (eslint.config.js)
• Dropped ESLint plugins — Removed eslint-config-standard, eslint-plugin-node, eslint-plugin-standard, and eslint-plugin-import (incompatible with ESLint v10)
• Minimum Node.js version — Raised from >=18 to >=24

New Features

• OpenAPI 3.0 nullable support — nullable: true is automatically converted to Ajv v8-compatible type: [T, "null"]
• instancePath → dataPath normalization — Ajv v8's instancePath (JSON Pointer format) is automatically converted to dot-notation dataPath for backward compatibility
• Migration guide — Added comprehensive MIGRATION.md with error message mapping table

Dependency Updates

Core dependencies:

• ajv: ^6.12.6 → ^8.20.0
• ajv-formats: (new) ^3.0.1 — formats are now a separate package in Ajv v8
• ajv-keywords: ^3.5.2 → ^5.1.0
• openapi-schema-validator: ^3.0.3 → ^12.1.3
• js-yaml: ^3.14.1 → ^4.2.0
• decimal.js: ^10.3.1 → ^10.6.0

Dev dependencies:

• eslint: ^8.5.0 → ^10.5.0
• mocha: ^8.4.0 → ^11.7.6
• nyc: ^15.1.0 → ^18.0.0
• uuid: ^8.3.2 → ^14.0.0
• chai: ^4.3.4 → ^4.5.0
• chai-as-promised: ^7.1.1 → ^7.1.2
• eslint-plugin-n: ^11.1.0 → ^16.6.2
• eslint-plugin-promise: ^4.3.1 → ^7.3.0
• eslint-plugin-chai-friendly: ^0.6.0 → ^1.2.1

Code Changes

• Added normalizeAjvErrors utility to convert Ajv v8 errors (instancePath) to v6-compatible format (dataPath)
• Added convertNullable to transform OpenAPI 3.0 nullable: true to Ajv v8-compatible type arrays
• Updated addKeyword calls to use Ajv v8 API format ({ keyword, ...definition })
• Added ajv-formats support for Ajv v8 format validators
• Updated all Ajv instances to use addFormats(ajv) and strict: false for v8 compatibility
• Updated ajv-keywords import paths for v5 compatibility (keywords/ → dist/keywords/)
• Removed deprecated nullable option from Ajv configurations
• Updated all test assertions for Ajv v8 error message format and ordering changes
• Created eslint.config.js for ESLint v10 flat config format
• Excluded eslint.config.js from nyc coverage reporting

CI/CD Updates

• Updated Node.js test matrix from [18, 20, 22, 24] to [24]
• Set default Node.js version to 24
• Updated GitHub Actions to Node.js 24 compatible versions:
  • actions/checkout@v4 → @v5
  • actions/setup-node@v4 → @v6
  • actions/upload-artifact@v4 → @v6
  • actions/download-artifact@v4 → @v7
  • github/codeql-action/*@v1 → @v3
  • coverallsapp/github-action@master → @v2

Documentation

• Created comprehensive MIGRATION.md with:
  • Full error message mapping table (v2 → v3)
  • Breaking changes summary
  • Step-by-step migration guide
  • Troubleshooting tips
• Updated CHANGELOG.md with detailed v3.0.0-rc.1 changes
• Updated README.md with migration guide reference and Node.js >=24 requirement

Migration

See MIGRATION.md for a detailed migration guide including:

• Full error message mapping table
• Breaking changes explanation
• Step-by-step migration instructions
• Troubleshooting tips

Quick Migration Steps

1. Update your dependency: npm install api-schema-builder@3
2. Ensure Node.js >= 24
3. Search your codebase for string comparisons against validation error messages (see mapping table in MIGRATION.md)
4. Update error message assertions in your tests from "should" to "must"
5. Check error ordering — if you compare full error arrays with deep equality, the order may have changed
6. Update ajv-keywords imports if you use them directly: keywords/ → dist/keywords/

Testing

• All existing tests updated to match Ajv v8 error format
• Test coverage maintained at >95% lines, >90% branches
• Verified on Node.js 24

Checklist

• All tests pass
• Coverage maintained
• Documentation updated (README, CHANGELOG, MIGRATION.md)
• CI/CD updated to Node.js 24
• Breaking changes documented
• Migration guide provided

[marioburatto]

@kibertoad, @kobik, @ilanKushnir

Hi maintainers,

I've opened this PR (#116) to upgrade this library to Ajv v8 and modernize the project infrastructure. This is a major version bump (v3.0.0-rc.1) that brings the library back on track with current Node.js and dependency versions.

Key highlights:

• Upgraded Ajv from v6 to v8 (released 2021, now on v8.20.0)
• Raised minimum Node.js to 24 (current LTS)
• Modernized CI/CD with latest GitHub Actions
• Added comprehensive migration guide (MIGRATION.md)
• All tests passing with maintained coverage

This library is important to my project and I imagine many others depend on it. The upgrade addresses several security concerns from outdated dependencies and ensures compatibility with modern Node.js versions.

I've included detailed documentation, a full error message mapping table for migration, and all tests have been updated to pass. The changes are well-tested and documented.

Would appreciate a review when you have a chance. Happy to discuss any concerns or make adjustments as needed.

Thanks for maintaining this project!